API программный интерфейс Интернет-радио

Документация к API

В этом разделе показано, как использовать API нашей панели управления Интернет-радио для получения информации о состоянии эфира и других данных у себя на сайте. Используя наш API Вы можете строить свои собственные скрипты и модули для сайта своего радио.

В результате запроса к API будут выданы данные в формате JSON/JSONP.

Вызов API происходит по адресу <адрес Вашей панели на сервере>/api/<параметры>, например: http://demo.radio-tochka.com:8080/api/djs/?limit=1.

На настоящий момент реализовн API к следующим ресурсам:

  • Сервер/Server - получение информации о серверах, созданных в панели управления
  • Канал/Channel - информация о каналах сервера (получения списка, битрейта и прочих данных)
  • История/History - история эфира
  • Диджей/DJ - информация о диджеях радио

Для каждого из ресурсов можно запросить их список, например:

  • /api/servers/ - получение списка серверов
  • /api/channels/ - список всех каналов
  • /api/djs/ - получение списка диджеев
  • /api/history/ - история эфира

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

{
    "meta": {
        "limit": <количество объектов на странице>,
        "next": <uri для получения слудеющей страницы>,
        "offset": <начиная с какого элемента нужно отдавать данные>,
        "previous": <uri для получения предыдущей страницы>,
        "total_count": <общее количество элементов>
    },
    "objects": [
        <объект 1>,
        <объект 2>,
        ...
        <объект n>
    ]
}

Можно изменять количество объектов в запросе и устанавливать лимиты выборки, манипулируя параметрами limit и offset.

Например:

  • /api/djs/?limit=1 - получить только одного (первого) диджея
  • /api/history/?limit=1 - текущая песня в эфире (первая в истории эфира)

Фильтрации запросов

Параметры фильтраций передаются как параметры GET-запроса.

Фильтры нужны для того, чтобы выбрать не все объекты, а конкретные, например список только активных диджеев. Для объектов доступны следующие фильтры:

  • Server - нет фильтров
  • Channel - [server <id сервера>]
  • History - [server <id сервера>]
  • DJ - [server <id сервера> | active <0|1> | connected <0|1> | on_air <0|1>], где:
    • active - включен ли диджей (может ли он подключаться к эфиру)
    • connected - подключен ли диджей в данный момент
    • on_air - если равно 1, значит диджей подключен, активен и сейчас находится в эфире.

Примеры фильтраций:

  • /api/djs/?limit=1?server=1&on_air=1 - получить данные о диджее в эфире на сервере 1
  • /api/channels/?server=1 - получить список каналов сервера 1
  • /api/history/?server=1&limit=1 - текущая песня в эфире сервера 1

Пример использования API

В этом простом примере мы будем запрашивать каждые 5 секунд название текущего трэка на радио и выводить его на странице.

<html>
  <body>
    <div id="track"></div>

    <script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
    <script>
     $( document ).ready(function() {
         function updateTrack(){
             $.ajax({
                 // Дополнительно передается два параметра
                 // callback & format для получения данных
                 // в формате JSONP. Это позволит преодолеть CORS ограничение
                 url: "http://demoaccount.s02.radio-tochka.com:8080/api/history/?server=1&limit=1&callback=callback&format=jsonp",
                 jsonp: "callback",
                 dataType: "jsonp",
                 method: "GET",
                 success: function( response ) {
                     var trackTitlte = response.objects[0].metadata;
                     $("#track").text(trackTitlte);
                 }
             });
         }
         updateTrack();
         setInterval(updateTrack, 5*1000);
     });
    </script>
  </body>
</html>