Подключение к внешнему REST API
Описание ситуации
Для пользователей, которые хотят подключиться по REST API есть возможность сделать это используя наш отдельный ресурс. На этом ресурсе пользователь ознакомиться с методами и типами запросов, которые позволят ему подключиться и получать данные от платформы SmartPlayer.
Работа портала
Данный раздел построен на базе Swagger Plugin и позволяет не только ознакомиться с информацией для подключения по REST API, но и опробовать описанные методы, получая реальный результат. Также технически продвинутые пользователи могут протестировать описанные методы используя Postman, если он является более привычным инструментом.
Сценарий использования
Предполагается что взаимодействие с порталом будет происходить в определённой последовательности. Сценарий предполагаемого использования:
- Авторизация на портале.
- Выбор нужного сервера для тестирования запросов.
- Получение токена для использования кнопки "Authorize".
- Выбор нужного метода и изучение информации о нём.
- По кнопке "Try it out" отправка запроса.
- Получение и просмотр ответа от сервера.
- Изучение раздела "Schemas".
Информация на портале
После авторизации на портале пользователю откроется основная страница, на которой ему отобразится следующая информация:
На странице портала отображается информация о:
- контактной информации с командой SmartPlayer;
- списке доступных для тестирования серверов;
- кнопка "Atuhorize" (подробнее о работе с кнопкой ниже на странице)
- список методов;
- раздел "Schemas" (нужно пролистать страницу вниз до конца)
Выбор сервера
Для тестирования запросов с методами пользователю необходимо выбрать один из представленных в списке методов. Каждый сервер из списка имеет формат отображения: "название" + "краткое описание" (на английском языке).
Кнопка "Atuhorize"
При нажатии на кнопку "Authorize" пользователю откроется модальное окно с описанием и полем, в котором необходимо указана токен (bearer token) для авторизации. Чтобы получить данный токен можно прочитать инструкцию приложенную по ссылке в окне.
После введения токена авторизации необходимо нажать на кнопку "Close". Это вернёт пользователя на главную страницу, а также поменяет отображения иконки авторизации (выглядит как замок). Иконка будет подсвечена, а замок будет закрыт.
Информация о методах
На данный момент на портале представлено два вида методов:
- GET — используется для получения данных. Его параметры передаются в URL-ссылке. Метод безопасен (идемпотентен) и кэшируется.
- POST — отправляет данные в теле запроса. Используется для создания ил изменения ресурсов. Безопасен для конфиденциальной информации
Все методы представленные в списке имеют свою конечную точку пути (endpoint), который прописан после названия типа метода и выделяется жирным шрифтом.
Взаимодействие с методами
Список методов представленных на портале позволит пользователю провести тестовые подключения к северам и получать с них примеры информации и данных передаваемых через запросы. Успешный запрос отдаст информацию по выбранному методу и пользователь сможет просмотреть полученные результаты и понять как реагирует платформа SmartPlayer.
Области работы методов
На портале представлены методы работающие с различными частями системы. Ниже приведен список методов и область с которой они взаимодействуют:
- авторизация (Authorization);
- трансляции (Broadcast);
- контент (Content);
- оповещения (Notifications);
- IP-телевидение (IP-TV);
- пользователь (User);
- настройки (Settings);
- расписания (Schedule);
- устройства (Устройства)
Список методов
Ниже будет представлен список методов с переводом краткого описания в порядке описанном ранее:
- Авторизация:
- Вход в серверное приложение.
- Трансляции:
- Импортировать трансляцию.
- Отправьте событие для изменения страницы трансляции.
- Получить все трансляции для компании пользователя.
- Получить трансляцию по ID.
- Получить трансляцию по заголовку.
- Контент:
- Загрузить файл.
- Загрузка нескольких файлов.
- Загрузка файла в видеоредактор.
- Загрузка файлов.
- Оповещения:
- Загрузка истории действий пользователей.
- IP-телевидение:
- Экспортировать CSV-файлы для IPTV.
- Импортировать CSV-файлы в IPTV.
- Пользователь:
- Обновление фотографии пользователя.
- Создать нового пользователя.
- Отправить ссылку для сброса пароля.
- Настройки:
- Загрузить шрифт.
- Расписания:
- Экспортировать расписание в архиве
- Устройства:
- Получить устройство digital signage по IP-адресу
- Получить все устройства digital signage компании
- Обновить таймеры digital signage
Информация внутри метода
Каждый метод можно развернуть по иконке ">" и просмотреть его содержимое. Внутри метода отображается следующая информация:
- краткое описание метода (на английском);
- параметры (Parameters) запроса;
- тело запроса (Request body), с возможность просмотра примера значений (Example Values) или схемы (Schema);
- ответы (Responses) с кодами ответов.
Кнопка "Try"it out
Кнопка "Try it out" (попробуйте это) позволяет пользователю попробовать сделать запрос к любому выбранному ранее серверу.
При ее нажатии интерфейс немного меняется предлагая пользователю либо тело запроса, либо строку для ввода значения параметра. Кнопка "Try it out" меняется на кнопку "Cancel" (удалить), которая возвращает метод в исходное состояние.
Отправить запрос можно кликнув по кнопке "Execute". Ответ приходит сразу же по нажатию.
Ответ будет отображён в разделе "Responses". Запрос можно повторить снова нажав кнопку "Execute" и введя другой параметр. Или очистить содержимое запроса нажав на кнопку "Clear".
Схемы (Schemas)
Данный раздел описывает информацию о структуре данных, с которыми работает API.
Понимание схемы данных даёт пользователю API:
- Понимание форматов ответа.
- Понимание форматов запроса.
- Типы данных.
- Обязательность полей.
- Понимание наличия/отсутствия вложенных структур.
- Возможность повторного использования моделей.
- Понимание ошибок.
Чтобы развернуть любую вкладку раздела пользователю нужно нажать на иконку ">". После открытия вкладки пользователь увидит два столбца:
- первый столбец — название параметра;
- второй столбец — тип данных параметра.
В некоторых случаях под типом данных (во втором столбце) располагается описание или пример (example).
Также присутствует ситуация, когда пользователь вместо типа данных получает еще одну вкладку (называние + ">"). Необходимо просто разворачивать доступные вкладки по иконке ">". Вложенностей такого формата может быть несколько.
Взаимодействие через Postman
Для продвинутых пользователей доступен альтернативный вариант — обращение к ресурсам компании SmartPlayer через Postman.
Установив и запустив Postman пользователю необходимо нажать на кнопку "New" и выбрать вариант типа API. В данном случае это "HTTP" (он же REST).
После необходимо выбрать тип запроса из списка и вставить нужный URL-адрес (название сервера + /название конечно точки). В данном примере URL-адрес будет: https://develop-api.smartplayer.org/login.
В зависимости от запроса настроить параметры в разделе "Headers"(параметры указаны на портале в теле метода) и тело запроса "Body" → "Row" (если необходимо, также в теле описания метода на портале).
Далее нажимаем на кнопку "Send" и моментально получаем ответ, который расположен в нижней части экрана.
Сравниваем его с информацией указанной на портале.
Видеоинструкция
Подключение к внешнему REST API
Дополнительная информация
Если данная статья не помогает использовать функционал по назначению или после её прочтения остаются вопросы, их можно задать в разделе "Обсуждения" вверху страницы.
Найти дополнительную информацию можно на странице Как взаимодействовать пользователю с разделом "Обсуждения"
