Registry API

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

Оглавление

Общая информация

Регистратура — точка входа для всех приложений Инетры, позволяющая определить:

Синхронизация времени

Клиент может синхронизировать локальное время с серверным на основе информации о часовом поясе и времени генерации ответа, полученного из HTTP–заголовка Date (см. RFC822).

Данный прием позволяет выполнить синхронизацию времени с некоторой ошибкой (ввиду сетевых задержек).

Расположение API

Корневой адрес API — http://api.peers.tv/registry/2/. Формат ответа зависит от суффикса запроса:

Цифра 2 символизирует версию API и может меняться в дальнейшем.

Коды ответов

API возвращает результат работы в HTTP–коде и имеет следующие стандартные коды ответов:

Код Значение
200 Успешное обращение к методу
400 В запросе отсутствует обязательные параметры
501 Метод не реализован

Сервисы контрагентов

Каждый контрагент имеет список сервисов, которые предоставляются им на определенном множестве территорий. Виды сервисов, которые можно найти с помощью Регистратуры перечислены в таблице ниже. Сервис может иметь несколько способов доставки. К примеру, IP–телевидение может поставляться как с помощью multicast, так и с помощью других средств, вроде HTTP Live Streaming или RTSP.

Код Идентификатор Название Провайдер Возможные API Описание
0 films Каталог фильмов CN.ru Инетра и партнеры Films API С помощью API можно получить список фильмов, описания и ссылки для загрузки и просмотра из файлообменной сети Пирс.
1 iptv IP–телевидение Контрагент IPTV IP–телевидение, может распространяться различными транспортами.
2 peerstv Peers.TV Инетра и партнеры PeersTV API С помощью API можно получить список каналов, расписание для каждого из них, а также ссылки на эфир и записи телепередач для просмотра из файлообменной сети Пирс.
3 peers Файлообменная сеть Пирс Инетра и партнеры NMDC, Registry API С помощью API можно обнаружить доступные хабы и подключиться в качестве клиента.
4 tv_guide Телепрограмма Инетра Media Guide API С помощью данного сервиса можно получить информацию о канале по его идентификатору, а также расписание на прошлое и будущее время. Учитывается территория и, как следствие, ее часовой пояс.
5 notification Уведомления Инетра Notifications API С помощью API приложения рассылают пользователям уведомления о событиях.
6 tracking Трекинг событий Инетра Tracking API С помощью API приложения могут регистрировать происходящие события для последующей их обработки.
7 auth Аутентификация пользователя и авторизация приложения Инетра и партнеры Auth API
8 user_data Данные пользователя Инетра User Data API
9 user_data_merge Слияние пользовательских данных Инетра User Data Merge API устарело с версии 2.25.2
10 media_locator Нахождение источников вещания Инетра и партнеры Media Locator API
11 pinger HTTP pinger Кто угодно HTTP С помощью данного API контрагент может определять активность приложений в своей сети. Приложение периодически отправляет запросы на адрес, указанный в location.
12 radio Радио Инетра и партнеры Radio Предоставляет список источников вещания каналов радио.
13 catalogue Медиа Каталог Инетра Catalogue API Предоставляет информацию о коллекциях медийных элементов.
14 promo Промо Инетра Promo API устарело с версии 2.28
15 bytefog ByteFog Инетра ByteFog API Предоставляет узлам сети ByteFog поиск точек входа для получения потокового вещания.
16 portchecker PortChecker Кто угодно PortChecker API Предоставляет проверку возможности получения входящих соединений.
17 internet Доступ к сети Интернет Кто угодно отсутствует Описывает услугу «Доступ к сети Интернет»
18 registry Регистратура Инетра Registry API Предоставляет информацию о доступных сервисах
19 money_miner Конфигуратор рекламы Инетра Money Miner API Предоставляет информацию о рекламных сетей для баннерных мест
20 launcher Вывод афиш в лаунчер на приставке Инетра и ЭГ Launcher API Предоставляет список афиш для отображения в лаунчере на приставке
21 appconfig Конфигуратор приложений Инетра Appconfig API Предоставляет клиенту возможность получать информацию о конфигурационных параметрах.
22 promo_block Промоблок Инетра PromoBlock API Предоставляет данные для отображения промоблока (слайдера/карусели)
23 promocode Промокоды Инетра [Promocode API] Ввод и проверка промокодов
24 feed Ленты Инетра [Feed API] Выдача лент контента в приложениях
25 purchases Покупки Инетра [Purchases API] Получения данных о покупках в приложениях
26 gismeteo Погода Гисметео Gismeteo API Прогноз погоды от Гисметео

Версионирование сервисов

Каждый сервис, выданный Регистратурой, может поддерживать одну или несколько версий протоколов взаимдействия.

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

Для информационных сервисов допускается поддерживать только актуальную версию, для сервисов контрагентов–партнеров (IPTV, MediaLocator, Auth, Radio) рекомендуется поддерживать все существующие версии (на момент выпуска клиента).

Резервирование сервисов

В целях резервирования сервисов метод whereami может выдать несколько альтернативных описаний для каждой версии сервиса, упорядоченные в рамках версии по топологической и/или географической близости;

При возникновении критических ошибок при работе с сервисом, клиент должен обратиться по адресу, сформированному на основе альтернативного описания используемой версии сервиса, а описание версии, на которой произошла ошибка, пометить как временно недоступное для обращений на непродолжительное время (не более 10 минут).

Под критическими ошибками стоит понимать:

Пример

Частичная выдача метода whereami:

{
  ...
  "services":
   [
     ...
     {
        "type": "user_data",
        "contractor":
        {
          "contractorId": 2
        },
        "name": "Данные пользователя",
        "apiVersions":
        [
           {
              "majorVersion": 1,
              "location": "http://msk.api.peers.tv/userdata/1/"
           },
           {
              "majorVersion": 1,
              "location": "http://nsk.api.peers.tv/userdata/1/"
           },
           {
              "majorVersion": 1,
              "location": "http://vl.api.peers.tv/userdata/1/"
           },
         ]
       },
     ...
   ]
}

В данном случае для сервиса «Данные пользователя» выдано 3 описания версии с номером 1. При выполнении запроса к сервису клиент должен выбрать первое описание версии, которое соответствует размещению сервиса в Московском датацентре. При возникновении критической ошибки клиент должен переключиться на следующее описание версии сервиса и повторить запрос.

Резервирование Регистратуры

Для резервирования корневого сервиса «Регистратура» предусмотрена выдача описания сервиса в методе whereami. К данному сервису применимы описанные выше принципы резервирования сервисов.

При получении описания сервиса Регистратура, клиент должен переключиться с фиксированного на полученное описание сервиса и сохранить его для последующих обращений. Клиент должен использовать фиксированное описание сервиса Регистратура при возникновении нештатных ситуаций в работе метода whereami при использовании выданного описания сервиса. К нештатным ситуациям относятся:

Методы

whereAmI — где я

параметр значение по умолчанию значение
territory автоматически определенный идентификатор территории
contractor автоматически определенный идентификатор оператора
client автоматически определенный идентификатор клиента

Возвращает информацию о месторасположении клиента и доступных ему веб–службах контрагентов. Если заданы дополнительные параметры, абонент рассматривается, как будто он находится на указанной территории и/или провайдере.

Возможные идентификаторы клиента:

идентификатор клиента расшифровка
cn.ru-android Приложение CN.ru (также известное как Peers) на платформе Android
cn.ru-desktop Приложение CN.ru (также известное как Peers) на настольных системах
cn.ru-web Сайт CN.ru
peers.tv-android Приложение Peers.TV на платформе Android
peers.tv-ios Приложение Peers.TV на платформе iOS
peers.tv-stb-dune Приложение Peers.TV на приставке DUNE
peers.tv-tv-lg Приложение Peers.TV на телевизоре LG
peers.tv-tv-panasonic Приложение Peers.TV на телевизоре Panasonic
peers.tv-tv-philips Приложение Peers.TV на телевизоре Philips
peers.tv-tv-samsung Приложение Peers.TV на телевизоре Samsung
peers.tv-tv-sony Приложение Peers.TV на телевизоре Sony
peers.tv-web Сайт Peers.TV

Формат ответа: сообщение WhereAmI.

Замечания:

territories — получение списка территорий

параметр значение по умолчанию значение
id отсутствует список идентификаторов территорий, разделенных символом запятая (,)
territory 0, т.е. «весь мир» идентификатор территории, для которой запрашиваются дочерние
contractor отсутствует идентификатор контрагента, которому должны принадлежать запрашиваемые территории
q отсутствует строка, с которой начинается название территории
parents 0 количество родительских территорий, возвращаемых в запросе

Ответ: сообщение TerritoryList.

Замечания:

neighborhood — информация о соседних ареалах

параметр значение по умолчанию значение
area автоматически определенный идентификатор ареала

Формат ответа: сообщение AreaList.

hubList — хабы ареала

параметр значение по умолчанию значение
area отсутствует идентификатор ареала

Формат ответа: сообщение HubList.

Если параметр area не задан, возвращаются все хабы всех ареалов.

hubIsolations — изоляция между хабами ареала

параметр значение по умолчанию значение
area отсутствует идентификатор ареала

Формат ответа: сообщение HubIsolationList.

prefixes — IP–префиксы контрагента

параметр значение по умолчанию значение
contractor отсутствует идентификаторы контрагента
territory отсутствует идентификаторы территории

Формат ответа: сообщение PrefixList.

Замечания

Например, чтобы получить список префиксов контрагентов 1 и 2, которые находятся на территории с идентификатором 6, необходимо в данном запросе передать параметры contractor=1,2&territory=6.

contractors — получение списка контрагентов

параметр значение по умолчанию значение
id отсутствует список идентификаторов контрагентов, разделенных символом запятая (,)
area отсутствует идентификатор ареала
territory отсутствует идентификатор территории
q отсутствует строка, содержащая часть названия или бренда контрагента
services отсутствует строковые идентификаторы сервисов, перечисленные через запятую

Формат ответа: сообщение ContractorList.

Замечания:

knownInfo — информация от пользователя (устарело с версии 2.18)

Формат запроса: сообщение KnownInfo.

Запрос передается методом POST в формате, соответствующем суффиксу запроса.

Запрос используется для новых контрагентов, информации о которых нет в Регистратуре, а также для сбора данных от пользователей о неверных результатах определения контрагента и территорий. Данная информация сохраняется на сервере и используется в качестве справочной при создании нового контрагента на основе данных, введенных пользователем. Во время сохранения информации в базе данных также фиксируется IP адрес источника запроса, а также информация из RIPE на момент запроса.

Идентификатор устройства пользователя позволяет модератору Регистратуры отделять запросы одного и того же пользователя в случае преднамеренной отправки множества данных и/или информационного мусора.

Форматы сообщений

WhereAmI — Где я

message WhereAmI {
  optional ContractorInfo contractor = 1;
  repeated TerritoryInfo territories = 2;
  repeated APIInfo apis = 3 [deprecated=true];
  repeated Service services = 4;
  optional string ipAddress = 5;
} 

message APIVersion {
  optional uint32 majorVersion = 1;
  optional uint32 minorVersion = 2;
  optional string location = 3;
  optional string params = 4;
}

message APIInfo {
  enum APIType {
    FILMS = 0;        // Films API
    IPTV = 1;         // телевидение провайдера
    TV_RECORDS = 2;   // контент Peers.TV
  }

  optional APIType apiType = 1;
  optional string name = 2;
  repeated APIVersion apiVersions = 3;
}

message Service {
  enum Type {
    option allow_alias = true;

    FILMS = 0 [(CN.string_value) = "films"];
    IPTV = 1 [(CN.string_value) = "iptv"];
    PEERSTV = 2 [(CN.string_value) = "peerstv"];
    PEERS = 3 [(CN.string_value) = "peers"];
    TV_GUIDE = 4 [(CN.string_value) = "tv_guide"];
    MEDIA_GUIDE = 4 [(CN.string_value) = "tv_guide"];
    NOTIFICATION = 5 [(CN.string_value) = "notification"];
    TRACKING = 6 [(CN.string_value) = "tracking"];
    AUTH = 7 [(CN.string_value) = "auth"];
    DATA = 8 [(CN.string_value) = "user_data"];
    USERS_MERGE = 9 [(CN.string_value) = "user_data_merge"];
    MEDIA_LOCATOR = 10 [(CN.string_value) = "media_locator"];
    PINGER = 11 [(CN.string_value) = "pinger"];
    RADIO = 12 [(CN.string_value) = "radio"];
    CATALOGUE = 13 [(CN.string_value) = "catalogue"];
    PROMO = 14 [(CN.string_value) = "promo"];
    BYTEFOG = 15 [(CN.string_value) = "bytefog"];
    PORTCHECKER = 16 [(CN.string_value) = "portchecker"];
    // 17 reserved for "internet"
    REGISTRY = 18 [(CN.string_value) = "registry"];
    MONEY_MINER = 19 [(CN.string_value) = "money_miner"];
    LAUNCHER = 20 [(CN.string_value) = "launcher"];
    APPCONFIG = 21 [(CN.string_value) = "appconfig"];
    PROMO_BLOCK = 22 [(CN.string_value) = "promo_block"];
  }

  optional Type type = 1;
  optional ContractorInfo contractor = 2;
  optional string name = 3;
  repeated APIVersion apiVersions = 4;
  optional uint32 pingInterval = 5;
  optional uint32 id = 6;
}

Замечания:

ContractorInfo, ContractorList — информация о контрагенте

message ContractorInfo {
  message ContractorImage {
    enum ProfileType {
      SQUARE_SOLID = 1;
      LAUNCHER = 2;
      LAUNCHER_KIDS = 3;
      PROGRESSBAR_POSITION = 4;
      PROGRESSBAR_POSITION_KIDS = 5;
      LAUNCHER_VERTICAL = 6;
      LAUNCHER_VERTICAL_KIDS = 7;
    }

    optional uint32 width = 3;
    optional uint32 height = 4;
    optional string URL = 5;
    optional ProfileType profile = 6;
  }

  enum PrivateOfficeIdiom {
    WEB = 0;
    TV = 1;
    MOBILE = 2;
  }

  optional uint32 contractorId = 1;
  optional string name = 2;
  repeated ContractorImage images = 3;
  optional string brandName = 4;
  optional string privateOfficeURL = 5;
  optional string callCenterNumber = 6;
  repeated string partnerTags = 7;
  repeated PrivateOfficeIdiom supportedOfficeIdioms = 8;
}

message ContractorList {
  repeated ContractorInfo contractors = 1;
}

Описание атрибутов сообщения ContractorInfo:

Описание атрибутов сообщения ContractorImage:

TerritoryInfo, TerritoryList — информация о территории

message TerritoryInfo {
  optional uint32 territoryId = 1;
  optional string name = 2;
  optional uint32 parentId = 3;
  optional bool isLeaf = 4;
  optional TerritoryInfo parent = 5;
  optional int32 timezone = 6;
  repeated string content_languages = 7;
}

message TerritoryList {
  repeated TerritoryInfo territories = 1;
}

Замечания:

Замечание: для часового пояса не учитывается переход на зимнее/летнее время, а также в некоторых случаях значение может отсутствовать, например, когда для территории может быть определено более одного часового пояса (пример: Россия, СФО).

Area, AreaList — список ареалов

message AreaList {
  repeated Area areas = 1;
}

message Area {
  optional uint32 areaId = 1;
  optional string name = 2;
  optional uint32 cost = 3;
}

Замечания:

Hub, HubList — список хабов

message Hub {
  optional string name = 1;
  message IPAddress {
    optional string hostname = 1;
    optional uint32 port = 2;
  }

  repeated IPAddress addresses = 2;
  optional IPAddress nodeAddress = 3;
  optional AreaList areas = 4;
}

message HubList {
  repeated Hub hubs = 1;
}

Замечания:

HubIsolation, HubIsolationList — изоляция между хабами

message HubIsolationList {
  message HubIsolation {
    optional string fromHub = 1;
    optional string toHub = 2;

    enum TTHSearch {
      NONE = 0;
      WITHPRIO = 1;
      FULL = 2;
    }
    optional TTHSearch tthSearch = 3;
    optional bool textSearch = 4;
    optional bool u2u = 5;
  }

  repeated HubIsolation hubIsolations = 1;
}

Замечания:

Prefix, PrefixList — список IP–префиксов

message PrefixList {
  message Prefix {
    optional string CIDR = 1;
    optional string NAT = 2;
    optional bool peersAccess = 3;
    optional ContractorInfo contractor = 4;
    repeated TerritoryInfo territories = 5;
  }

  repeated Prefix prefixes = 1;
}

Замечания:

KnownInfo — информация от пользователя

message KnownInfo {
  optional uint32 contractorId = 1;
  optional string contractorName = 2;
  optional uint32 territoryId = 3;
  optional string territoryName = 4;
  optional uint32 parentTerritoryId = 5;
  optional string iptvPlaylistAddress = 6;
  optional string uid = 7;
}

Замечания:

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

Изменения в версии 2.0

Изменения в версии 2.1

Изменения в версии 2.2

Изменения в версии 2.3

Изменения в версии 2.4

Изменения в версии 2.5

Изменения в версии 2.6

Изменения в версии 2.7

Изменения в версии 2.8

Изменения в версии 2.9

Изменения в версии 2.10

Изменения в версии 2.11

Изменения в версии 2.12 (TVREC–181, TVREC–92)

Изменения в версии 2.12.1

Изменения в версии 2.13 (TVREC–251)

Изменения в версии 2.13.1

Изменения в версии 2.14 (TVREC–321)

Изменения в версии 2.15 (TVREC–341)

Изменения в версии 2.16 (TVREC–274)

Изменения в версии 2.17 (TVSET–594)

Изменения в версии 2.18 (TVREC–378)

Изменения в версии 2.18.1

Изменения в версии 2.18.2

Изменения в версии 2.18.3

Изменения в версии 2.18.4

Изменения в версии 2.19 (TVREC–425)

Изменения в версии 2.20 (BYTEFOG–291)

Изменения в версии 2.20.1

Изменения в версии 2.21

Изменения в версии 2.21.1

Изменения в версии 2.21.2 (TVREC–565)

Изменения в версии 2.21.3 (TVREC–628)

Изменения в версии 2.22 (TVREC–409)

Изменения в версии 2.23 (TVREC–665)

Изменения в версии 2.24 (TVREC–697)

Изменения в версия 2.24.1

Изменения в версия 2.25 (TVREC–668)

Изменения в версии 2.25.1

Изменения в версии 2.25.2 (TVREC–720)

Изменения в версии 2.25.3

Изменения в версии 2.26.0 (TVREC–790)

Изменения в версии 2.27.0 (TVREC–810)

Изменения в версии 2.28.0 (TVREC–907)

Изменения в версии 2.29.0 (TVREC–1077)

Изменения в версии 2.30.0 (TVREC–1269)

Изменения в версии 2.31.0 (TVREC–1348)

Изменения в версии 2.32.0 (PTVRND–184)

Изменения в версии 2.33.0 (PTVRND–894)

Изменения в версии 2.34.0

Изменения в версии 2.34.1

Изменения в версии 2.35.0

Изменения в версии 2.35.1