Описание REST API

API sovok.tv

Описание REST API

Сообщение Admin » 15 мар 2012, 13:04

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

Все запросы к REST API формируются по специально сформированному URL и имеют следущий вид:

httр://sovok.tv/api/<тип запроса>/<имя функции>?param1=value&param2=value

<тип запроса> = (xml|json|jsonp)
<имя функции> - имена функций и их описания представлены ниже.

Примеры:

Код: Выделить всё
http://sovok.tv/api/xml/get_url?cid=1
http://sovok.tv/api/json/get_url?cid=1
http://sovok.tv/api/jsonp/get_url?cid=1&callback=myfunc



Для идентификации и создании сессии было решено использовать стандартный механизм HTTP сессий с поддержкой COOKIE.
Первый вход - обязательное выполнение login. При корректном входе возвращается состояние, данные по клиенту и COOKIE которую необходимо передавать всегда при запросах. В COOKIE хранится идентификатор сессии и по ней организуется сессия. Далее, если запрос не будет содержать COOKIE, то это вызовет ошибку. Для корректного завершения сессии необходимо вызвать метод logout. Возможна передача параметров через url. Имя COOKIE при этом необходимо брать из ответа пакета sid_name.



Функции Sovok.tv REST API
Реализованы следущие функции API:
  • login
  • logout
  • account
  • channel_list
  • epg
  • epg3
  • epg_next
  • epg_next2
  • get_url
  • settings
  • settings_set
  • favorites_set
  • favorites
  • streamers

/login?login=<login>&pass=<password>
Для доступа к остальным функциям в первую очередь необходимо выполнять login


Входные параметры:
  • login - логин.
  • pass - пароль

Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="utf-8"?>
<response>
  <sid>[идентификатор сесии]</sid>
  <sid_name>[имя сессии]</sid_name>
  <account>
    <login>[логин]</login>
    <packet_name>[название пакета]</packet_name>
    <packet_expire>[дата и время истечения пакета]</packet_expire>
  </account>
  <servertime>[время формирования пакета]</servertime>
</response>



/account
Возвращает пакет аналогичный пакету функции /login


/logout
Вызов без параметров

Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="utf-8"?>
<response>
    <message>M_LOGOUT_OK</message>
    <servertime>1331811479</servertime>
</response>



/channel_list
Вызов без параметров

Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <groups>
    <item>
      <id>[идентификатор группы]</id>
      <name>[название группы]</name>
      <color>[CSS код цвета группы]</color>
      <channels>
        <item>
          <id>[идентификатор канала]</id>
          <name>[Название канала]</name>
          <is_video>[флаг потокового видео 0/1 1-видео, 0-радио]</is_video>
          <icon>[относительный путь к файлу иконки канала]</icon>
          <epg_progname>[название текущей телепередачи]</epg_progname>
          <epg_start>[дата и время начала текущей передачи]</epg_start>
          <epg_end>[дата и время окончания текущей передачи]</epg_end>
        </item>
        <item>
          <id>3</id>
          <name>Pоссия</name>
          <is_video>1</is_video>
          <icon>/img/ico/3.gif</icon>
          <epg_progname>ВЕСТИ-МОСКВА</epg_progname>
          <epg_start>1277807400</epg_start>
          <epg_end>1277808600</epg_end>
        </item>
      </channels>
    </item>
    <item>
    <id>2</id>
    <name>Новости</name>
    <color>#ef0000</color>
    <channels>
      <item>
        <id>6</id>
        <name>РТР Вести</name>
        <is_video>1</is_video>
        <icon>/img/ico/6.gif</icon>
        <epg_progname>"Вести. Сейчас. Главные события".</epg_progname>
        <epg_start>1277807400</epg_start>
        <epg_end>1277807700</epg_end>
      </item>
...
    </channels>
  </item>
</groups>
<servertime>1277807687</servertime>
</response>



/get_url?cid=<ИД канала>&protect_code=<код для закрытых каналов>

Входные параметры
  • cid - идентификатор канала полученный из channel_list
  • protect_code - цифровой код для закрытых каналов. Если канал защищен а код не передан, либо передан неверный код, то в тэге <url> возвращается "protected"

Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="UTF-8"?>
<response>
<url>http/ts://102.22.34.56:8000/?ticket=W4z3WFdoSRnMMXHgYFq...md4ZGtVyT6mjgqGZk%3D :http-caching=2000 :no-http-reconnect</url>
<servertime>1277808472</servertime>
</response>

url специально сгенерирован для проигрывания через VLC с соответствующими оптимизированными параметрами


/epg?cid=<идентификатор канала>&day=<DDMMYY>
Возвращает EPG канала cid на день - day

Входные параметры
  • cid - идентификатор канала полученный из channel_list
  • day - дата вида DDMMYY (Пример: 15 марта 2012 = 150312)

Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <epg>
    <item>
      <ut_start>[дата и время начала передачи]</ut_start>
      <progname>[название передачи]</progname>
      <t_start>[чч:мм начала передачи]</t_start>
    </item>
    <item>
      <ut_start>1277521800</ut_start>
      <progname>"Вся Россия".</progname>
      <t_start>15:00</t_start>
    </item>
    <item>
      <ut_start>1277522700</ut_start>
      <progname>"Диалоги о животных".</progname>
      <t_start>15:10</t_start>
    </item>
...
  </epg>
  <servertime>1277809426</servertime>
</response>



/epg3?dtime=<Дата и время старта EPG>&period=<на сколько часов вперед>
Выдача программы телепередач доступных каналов с времени указанного в dtime на следующие period часов.

Входные параметры:
  • dtime - unixtime начала EPG. По умолчанию выбирается текущий момент (по серверному времени)
  • period - на сколько часов вперед. По умолчанию 3 часа.

Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="UTF-8"?>
<response>
 <item>
  <id>2</id>
  <name>Первый</name>
  <epg>
    <item>
      <ut_start>1278944400</ut_start>
      <progname>"ХОЧУ ЗНАТЬ" с Михаилом Ширвиндтом</progname>
      <t_start>17:20</t_start>
    </item>
    <item>
      <ut_start>1278946200</ut_start>
      <progname>"ОБРУЧАЛЬНОЕ КОЛЬЦО" - многосерийный фильм Сериал.</progname>
      <t_start>17:50</t_start>
    </item>
  </epg>
  </item>
  <item>
    <id>3</id>
    <name>Pоссия</name>
    <epg>
      <item>
        <ut_start>1278942600</ut_start>
        <progname>"ТАЙНЫ СЛЕДСТВИЯ" - детективный сериал. В главной роли Анна Ковальчук</progname>
        <t_start>16:50</t_start>
      </item>
      <item>
        <ut_start>1278948600</ut_start>
        <progname>"КУЛАГИН И ПАРТНЕРЫ"</progname>
        <t_start>18:30</t_start>
      </item>
    </epg>
  </item>
  <item>
    <id>54</id>
    <name>Discovery</name>
   <epg>
   <item>
   <ut_start>1278943800</ut_start>
   <progname>"СМЕРТЕЛЬНЫЙ УЛОВ: ВРЕМЯ РАСПЛАТЫ"</progname>
   <t_start>17:10</t_start>
  </item>
  <item>
    <ut_start>1278947100</ut_start>
    <progname>"ДЕРЗКИЕ ПРОЕКТЫ: АРИЗОНСКИЕ "КАРДИНАЛЫ"</progname>
    <t_start>18:05</t_start>
  </item>
  <item>
    <ut_start>1278950400</ut_start>
    <progname>"РАЗРУШИТЕЛИ ЛЕГЕНД: СПЕЦВЫПУСК "ДЖЕЙМС БОНД". 1 часть"</progname>
    <t_start>19:00</t_start>
  </item>
 </epg>
</item>
<servertime>1278944765</servertime>
</response>



/epg_next?cid=<ИД канала>
Возвращает EPG на текущую и на 3 последующих телепередачи канала cid

Входные параметры
  • cid - идентификатор канала полученный из channel_list

Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <epg>
    <item>
      <ts>1294834800</ts>
      <progname>ХОЧУ ЗНАТЬ
        - с Михаилом Ширвиндтом
      </progname>
    </item>
    <item>
      <ts>1294836600</ts>
      <progname>"ОБРУЧАЛЬНОЕ КОЛЬЦО"
        - сериал Сериал.
      </progname>
    </item>
    <item>
      <ts>1294840200</ts>
      <progname>ФЕДЕРАЛЬНЫЙ СУДЬЯ</progname>
  </item>
  </epg>
  <servertime>1294835324</servertime>
</response>



/epg_next2?cids=<Ид канала>,<Ид канала>..
Возвращает EPG на текущую телепередачу для каналов cids

Входные параметры
  • cids - идентификаторы каналов через запятую полученные из channel_list

Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="utf-8"?>
<response>
  <epg>
  <item>
    <chid>170</chid>
    <progname>Теннис. Турнир "Masters" в Риме. Прямая трансляция</progname>
    <start>1337162400</start>
    <end>1337184000</end>
  </item>
  <item>
    <chid>167</chid>
    <progname>Мятежный дух</progname>
    <start>1337169900</start>
    <end>1337176200</end>
  </item>
  </epg>
 <servertime>1337169979</servertime>
</response>


/settings
Текущие настройки. Вызов без входных параметров.

Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <settings>
    <streamer>1</streamer>
    <timezone>+04:00:00</timezone>
    <buffer>10000</buffer>
    <deinterlace>0</deinterlace>
  </settings>
  <servertime>1341375372</servertime>
</response>

Где 0 = параметр не установлен.

/settings_set?<timezone|buffer|deinterlace|ratio|streamer|pin1&pin2>=<Значение>
Установка настроек

Входные параметры
  • timezone -часовой пояс. Возможные значения:
    Код: Выделить всё
    -12:00:00
    -11:00:00
    -10:00:00
    -09:00:00
    -08:00:00
    -07:00:00
    -06:00:00
    -05:00:00
    -04:30:00
    -04:00:00
    -03:30:00
    -03:00:00
    -02:00:00
    -01:00:00
    +00:00:00
    +01:00:00
    +02:00:00
    +03:00:00
    +03:30:00
    +04:00:00
    +04:30:00
    +05:00:00
    +05:30:00
    +05:45:00
    +06:00:00
    +06:30:00
    +07:00:00
    +08:00:00
    +09:00:00
    +09:30:00
    +10:00:00
    +11:00:00
    +12:00:00
    +13:00:00
    +14:00:00

  • buffer - время буферизации в миллисекундах. Возможные значения от 1000 до 100000
  • deinterlace - деинтерлейс. Возможные значения - '0','blend','bob','discard','linear','mean','x','yadif','yadif2x'
  • ratio - устанавливает соотношение сторон для конкретного канала. Значение должно быть равно <ИД канала>:<4:3|16:9|221:100> (1:4:3)
  • streamer - ID стриммера из streamers
  • pin1 - установка PIN1, 4 цифры, используется в паре с PIN2 для подтверждения настройки
  • pin2 - используется в паре и для подтверждения изменения PIN1, 4 цифры
Код: Выделить всё
Пример: http://sovok.tv/api/json/settings_set?ratio=1:4:3timezone=+04:00:00&buffer=3000&deinterlace=0

Код: Выделить всё
http://sovok.tv/api/xml/settings_set?pin1=<НОВЫЙ_PIN1>&pin2=<ТЕКУЩИЙ_PIN2>


Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <settings>
    <item>
      <name>ratio</name>
      <value>16:9</value>
      <channel>4</channel>
    </item>
    <item>
      <name>buffer</name>
      <value>3000</value>
    </item>
    <item>
      <name>deinterlace</name>
      <value>0</value>
    </item>
  </settings>
  <servertime>1337168386</servertime>
</response>


/favorites_set?cid=<ИД канала>
Добавляет\Удаляет канал из избранного
Входные параметры
  • cid - идентификатор канала полученный из channel_list
Повторный вызов функции для канала удаляет его из избранного

Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <message>
    <text>Favorite channel was set</text>
    <channel>19</channel>
    <code>2</code>
  </message>
  <servertime>1337168927</servertime>
</response>


/favorites
Список любимых каналов. Вызов без входных параметров.

Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <favorites>
    <item>
      <channel_id>2</channel_id>
    </item>
    <item>
      <channel_id>3</channel_id>
    </item>
  </favorites>
<servertime>1278944963</servertime>
</response>



/streamers
Список стрим-серверов. Вызов без входных параметров.


Возврат пакета вида:
Код: Выделить всё
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <streamers>
    <item>
      <id>1</id>
      <name>Streamer 1</name>
    </item>
    <item>
      <id>2</id>
      <name>Streamer 2</name>
    </item>
    <item>
      <id>3</id>
      <name>Streamer 3</name>
    </item>
  </favorites>
<servertime>1278944963</servertime>
</response>



Последнее обновление 04.07.2012
Admin
Администратор
 
Сообщения: 3142
Зарегистрирован: 15 мар 2012, 12:04

Re: Описание REST API

Сообщение alexlex » 17 мар 2012, 04:00

Доброго времени суток!

Спасибо за ресурс!

Я хотел бы написать плагин под Dune, но есть вопрос:

Что я делаю не так? :)

Отправляя запрос на вход ("http://sovok.tv/api/xml/login?login=[E-MAIL]&pass=[PASSWORD]") я получаю следующее:
Код: Выделить всё
<?xml version="1.0" encoding="utf-8"?>
<response><sid>4tp4sn2dikg9pjgi5eqev76e35</sid><sid_name>MWARE_SSID</sid_name><account><login>[LOGIN]</login><packet_name>Базовый</packet_name><packet_expire>1363476916</packet_expire></account><servertime>1331940916</servertime></response>


Тут все точно как и ожидается - по Вашей доке, но дальше у меня проблема
Я делаю следующее:
Код на php
Код: Выделить всё
        $ch = curl_init();

        curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 10);
        curl_setopt($ch, CURLOPT_USERAGENT, "Mozilla/5.0 (Windows NT 5.1; rv:7.0.1) Gecko/20100101 Firefox/7.0.1");
        curl_setopt($ch, CURLOPT_URL, "http://sovok.tv/api/xml/channel_list");
        curl_setopt($ch, CURLOPT_COOKIE, "MWARE_SSID");
           
        $content = curl_exec($ch);

        $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

        curl_close($ch);


И тут я получаю следующий ответ:
Код: Выделить всё
<br />
<b>Warning</b>:  session_start() [<a href='function.session-start'>function.session-start</a>]: The session id is too long or contains illegal characters, valid characters are a-z, A-Z, 0-9 and '-,' in <b>/usr/local/www/apache22/data/sovok.tv/restapi.php</b> on line <b>5</b><br />
<?xml version="1.0" encoding="utf-8"?>
<response><error><message>You are not logged</message><code>12</code></error><servertime>1331940916</servertime></response>


Помогите, пожалуйста.
А то, я когда увидел API, уже пообещал обладателям Dune на форуме hdtv.ru, что на выходных будет готово, а тут такая засада:)

Спасибо
alexlex
 
Сообщения: 17
Зарегистрирован: 16 мар 2012, 03:49

Re: Описание REST API

Сообщение Admin » 17 мар 2012, 11:14

Доброго.
Начнем по порядку ;)

http://sovok.tv/api/xml/login?login=[E-MAIL]&pass=[PASSWORD]"

Вместо e-mail так же можно указывать логин. С этим многим проще будет, думаю.

Код: Выделить всё
curl_setopt($ch, CURLOPT_COOKIE, "MWARE_SSID");

А в этой строке Вы передаете только "MWARE_SSID". Без идентификатора самой сессии. Должно быть так:"sid_name=sid".
Например:
Код: Выделить всё
curl_setopt($ch, CURLOPT_COOKIE, "MWARE_SSID=nmbqai575lih58b15chks0vtj4");


Или можно заменить на конструкциию:
Код: Выделить всё
curl_setopt($ch, CURLOPT_COOKIEFILE, '1.c'); //Куки раз
curl_setopt($ch, CURLOPT_COOKIEJAR,  '1.c');//Куки два

Где 1.с - файл записи кук.
Так все принятые куки будут передаваться при каждом запросе.

Успехов!
Admin
Администратор
 
Сообщения: 3142
Зарегистрирован: 15 мар 2012, 12:04

Re: Описание REST API

Сообщение alexlex » 17 мар 2012, 15:20

Спасибо большое!

Работает!!!

Осталось только EPG прикрутить.

Организационный вопрос: есть смысл выкладывать плагин для Dune у Вас на форуме?
alexlex
 
Сообщения: 17
Зарегистрирован: 16 мар 2012, 03:49

Re: Описание REST API

Сообщение Admin » 17 мар 2012, 15:37

Не за что. Обращайтесь.

Да, стоит. У нас все время спрашивают про Dune ;)
Admin
Администратор
 
Сообщения: 3142
Зарегистрирован: 15 мар 2012, 12:04

Re: Описание REST API

Сообщение fat30 » 17 мар 2012, 17:40

а можно попрасить когонибудь расжевать куда и какие изменения вносить ?
fat30
 
Сообщения: 3
Зарегистрирован: 17 мар 2012, 17:26

Re: Описание REST API

Сообщение fat30 » 17 мар 2012, 17:41

[quote="alexlex"]Спасибо большое!

Работает!!!
обьясни нам простым, куда чего нажимать :)
fat30
 
Сообщения: 3
Зарегистрирован: 17 мар 2012, 17:26

Re: Описание REST API

Сообщение alexlex » 17 мар 2012, 22:32

Для fat30
Думаю, что к завтрашнему утру плагин будет готов, и я его выложу.
alexlex
 
Сообщения: 17
Зарегистрирован: 16 мар 2012, 03:49

Re: Описание REST API

Сообщение fat30 » 18 мар 2012, 11:29

alexlex писал(а):Для fat30
Думаю, что к завтрашнему утру плагин будет готов, и я его выложу.


ждёмс.. :D
fat30
 
Сообщения: 3
Зарегистрирован: 17 мар 2012, 17:26

Re: Описание REST API

Сообщение alexlex » 18 мар 2012, 12:43

Да вот же он:)
http://forum.sovok.tv/viewtopic.php?f=8&t=11

Еще вечером был готов:)
alexlex
 
Сообщения: 17
Зарегистрирован: 16 мар 2012, 03:49

След.

Вернуться в REST API

Кто сейчас на конференции

Сейчас этот форум просматривают: нет зарегистрированных пользователей и гости: 1