ByteFog API

Статус документа

Оглавление

Введение

Этот API предназначен для получения программными клиентами проекта ByteFog информации о параметрах подключения к узлам-координаторам сети доставки потокового контента.

Описание API

Обращение к API должно производиться по протоколу HTTP с применением метода GET. API в настоящей версии состоит из одного запроса (entry_points). Ответы на запросы предлагаются в формате JSON. Выбрать формат ответа можно в поле формат_ответа URL запроса.

Формат URL запросов к API:

http://host/path/[версия]/[тип_запроса].[формат_ответа]?[параметры], где

• host — доменное имя или IP-адрес сервера API
• path — путь к API в URL, обычно равен bytefog
• версия — номер версии API (в настоящей спецификации описана версия 1)
• тип_запроса — тип запроса к API; в настоящей версии спецификации представлен только один тип —– entry_points.
• формат_ответа — тип формата ответа на запрос, в настоящей версии спецификации предлагаются один варианта формата: json.

В запросе клиент обязан указать свою версию и операционную систему, на которой он запущен. Для этого используется HTTP заголовок запроса User-Agent, заполняемый аналогично Tracking API.

Пример URL запроса к API:

http://api.peers.tv/bytefog/1/entry_points.json

Получить путь к API можно с помощью API регистратуры.

Запросы

Запрос entry_points

Предназначен для получения списка точек входа (координаторов) в сеть доставки потокового контента. Используется узлами сети ByteFog для подключения к потоку видео-контента (каналу телевидения в требуемом качестве).

Формат

Для описания формата ответа используется формат Google Protocol Buffers.

message EntryPoint {
  optional int32 priority = 1 [default = 0];
  optional uint32 weight = 2 [default = 1];
  optional string ipv4_address = 3;
  optional uint32 port = 4;
}

message EntryPointsResponse {
  repeated EntryPoint entry_points = 1;
}

EntryPoint — структура, описывающая одну точку входа

• priority — приоритет координатора. Чем больше число, тем больше приоритет. Координаторы с одинаковым приоритетом выбираются по весу (поле weight). Допускаются отрицательные значения.
• weight — вес координатора. Определяет вероятность выбора координатора среди координаторов с одинаковым приоритетом. Суммарная вероятность определяется суммой весов координаторов с одинаковым приоритетом. Вес определяет вероятность выбора координатора как (weight(i) /sum(weight)) Допускаются положительные значения больше 0. Если поле отсутствует вес брать равным 1.
• ipv4_address — IPv4-адрес координатора в формате x.x.x.x
• port — порт координатора

EntryPointsResponse — структура, описывающая ответ на запрос entry_points

• entry_points — список координаторов

Описание

При желании узла-клиента подключиться к видео-потоку в сети ByteFog он должен запросить список точек входа (узлов-координаторов), используемых далее для поиска источника потока.

Примеры

Пример запроса: http://api.peers.tv/bytefog/1/entry_points.json

Запрос check_for_updates

Предназначен для получения информации о последней версии узла, доступной для текущей операционной системы. Используется узлами сети ByteFog для определения необходимости обновления.

Формат ответа

message ApplicationVersion {
  optional string number = 1;
  optional string download_url = 2;
  optional string changelog = 3;
}

message CheckForUpdatesResponse {
  optional ApplicationVersion latest_version = 1;
  optional bool critical = 2;
}

ApplicationVersion — структура, описывающая одну версию приложения

• number — номер версии приложения, в формате MAJOR.MINOR.BUGFIX.BUILD
• download_url — ссылка, по которой доступна последняя версия приложения
• changelog — список изменений в версии, с HTML форматированием.

CheckForUpdatesResponse — структура, описывающая ответ на запрос check_for_updates

• latest_version — последняя доступная версия, заполняется при отличии текущей версии узла от последней доступной.
• critical — критичность обновления текущей версии приложения до последней доступной версии

Описание

Для определения устаревания версии модуля ByteFog, используется данный метод. Текущая версия модуля ByteFog и операционная система, на которой он работает, передается в заголовке User-Agent в том же формате, что используется в Tracking API.

Критичность обновления до последней версии определяется по критичности обновлений промежуточных версий модуля. Если между текущей версией модуля и последней доступной версией было хотя бы одно критическое обновление, последняя версия помечается также критичной к обновлению.

История версий

Версия 1.0

Начальная версия

Версия 1.0.1

Уточнены значения полей в ответе допустимые и по умолчанию.

Версия 1.1 (BYTEFOG–334)

Добавлен метод определения наличия обновлений.