Подключение к внешнему REST API/en

Description of the Situation

For users who want to connect via REST API, it is recommended to use our dedicated resource. On this resource, the user can test methods and requests that allow connection and data retrieval from the SmartPlayer platform.

The REST API portal is available here. You can request authorization credentials (login and password) by contacting us via the portal or your assigned SmartPlayer specialist. You can also write to this email.

Portal Operation

This section is built on the Swagger Plugin and allows not only to ознакомиться with connection information for REST API, but also to test described methods and receive real results. Advanced users can also test these methods using Postman.

Some methods described on the portal may not work correctly. The SmartPlayer team is aware of these issues and is working on fixing them.

Usage Scenario

It is assumed that interaction with the portal will follow a specific sequence. Usage scenario:

1. Authorization on the portal.
2. Selecting the required server for testing requests.
3. Obtaining a token to use the "Authorize" button.
4. Selecting the required method and reviewing its information.
5. Sending a request using the "Try it out" button.
6. Receiving and reviewing the server response.
7. Studying the "Schemas" section.

Details are provided below on the page.

Information on the Portal

After authorization, the user will see the main page displaying the following information:

Example of the REST API portal main page

The portal page includes information about:

• contact information for interacting with the SmartPlayer team;
• list of available servers for testing;
• "Authorize" button (details below);
• list of methods;
• "Schemas" section (scroll to the bottom of the page).

Example of portal page structure

Example of the "Schemas" section at the bottom

Server Selection

To test requests, the user must select one of the available servers. Each server is displayed as: "name" + "short description" (in English).

Example of available servers

The server list is not final. Users can connect manually via Postman to any server in the list or use other SmartPlayer servers such as "rc.smartplayer.org".

"Authorize" Button

Clicking the "Authorize" button opens a modal window where the user must enter a bearer token. Instructions for obtaining the token are provided via a link in the window.

Example of authorization modal window

After entering the token, click "Close". The authorization icon will change (lock icon will be closed and highlighted).

Example of authorization icon change

Hovering over the authorization icon will display an additional icon to copy the request to the clipboard.

Example of copy-to-clipboard icon

Methods Information

Currently, the portal provides two types of methods:

1. GET — used to retrieve data. Parameters are passed via URL. Safe (idempotent) and cacheable.
2. POST — sends data in the request body. Used to create or modify resources. Suitable for sensitive data.

Example of GET and POST methods

Each method has an endpoint specified after the method name and highlighted in bold.

Example of endpoint display

Interaction with Methods

The list of methods allows users to test connections and retrieve sample data. A successful request returns method data and allows analysis of SmartPlayer behavior.

Method Areas

Methods are grouped by system areas:

• Authorization;
• Broadcast;
• Content;
• Notifications;
• IP-TV;
• User;
• Settings;
• Schedule;
• Devices

Example of method list

Each method includes a short English description.

Example of method description

Methods List

Below is a list of methods with translated descriptions:

• Authorization:
  • Login to the server application.

Example of authorization method

• Broadcast:
  • Import broadcast.
  • Send event to change broadcast page.
  • Get all broadcasts.
  • Get broadcast by ID.
  • Get broadcast by title.

Example of broadcast methods

• Content:
  • Upload file.
  • Upload multiple files.
  • Upload file to video editor.
  • Upload files.

Example of content methods

• Notifications:
  • Upload user activity history.

Example of notification method

• IP-TV:
  • Export CSV files.
  • Import CSV files.

Example of IPTV methods

• User:
  • Update user photo.
  • Create user.
  • Send password reset link.

Example of user methods

• Settings:
  • Upload font.

Example of settings method

• Schedule:
  • Export schedule archive.

Example of schedule method

• Devices:
  • Get device by IP.
  • Get all devices.
  • Update timers.

Example of device methods

Method Details

Each method can be expanded to view:

• description;
• parameters;
• request body;
• responses.

Example of method details

"Try it out" Button

Allows sending requests.

Example of "Try it out"

After activation:

• interface changes;
• button becomes "Cancel".

Example of interface change

Send request via "Execute".

Example of "Execute"

Response appears in "Responses".

Example of response display

Схемы (Schemas)

Данный раздел описывает информацию о структуре данных, с которыми работает API.

Пример отображения раздела "Schemas"

Понимание схемы данных даёт пользователю API:

1. Понимание форматов ответа.
2. Понимание форматов запроса.
3. Типы данных.
4. Обязательность полей.
5. Понимание наличия/отсутствия вложенных структур.
6. Возможность повторного использования моделей.
7. Понимание ошибок.

Чтобы развернуть любую вкладку раздела, пользователю нужно нажать на иконку ">". После открытия вкладки пользователь увидит два столбца:

• первый столбец — название параметра;
• второй столбец — тип данных параметра.

Пример отображения отображаемой информации на открытой вкладке

В некоторых случаях под типом данных (во втором столбце) располагается описание или пример (example).

Пример отображения описания или примеров

Также присутствует ситуация, когда пользователь вместо типа данных получает ещё одну вкладку (название + ">"). Необходимо просто разворачивать доступные вкладки по иконке ">". Вложенностей такого формата может быть несколько.

Пример отображения вложенных вкладок

Взаимодействие через Postman

Для продвинутых пользователей доступен альтернативный вариант — обращение к ресурсам компании SmartPlayer через Postman.
Установив и запустив Postman, пользователю необходимо нажать на кнопку "New" и выбрать вариант типа API. В данном случае это "HTTP" (он же REST).

Пример отображения интерфейса Postman

После необходимо выбрать тип запроса из списка и вставить нужный URL-адрес (название сервера + /название конечной точки). В данном примере URL-адрес будет: https://develop-api.smartplayer.org/login.

Пример отображения тип запроса и URL-адреса

Настроить параметры в разделе "Headers", по необходимости (параметры указаны на портале в теле метода) и тело запроса "Body" → "Raw" (если необходимо, также в теле описания метода на портале).

Пример отображения "Headers" и "Body" → "Row"

Также в зависимости от запроса может понадобиться настроить авторизацию (раздел "Authorization" в Postman). Она реализована через "bearer token".

Далее нажимаем на кнопку "Send" и моментально получаем ответ, который расположен в нижней части экрана.

Пример отображения кнопки "Send" и ответа по запросу

Сравниваем его с информацией, указанной на портале.

Видеоинструкция

Подключение к внешнему REST API

Дополнительная информация

Если данная статья не помогает использовать функционал по назначению или после её прочтения остаются вопросы, их можно задать в разделе "Обсуждения" вверху страницы.

Пример отображения вкладки "Обсуждения" на wiki-странице

Найти дополнительную информацию можно на странице Как взаимодействовать пользователю с разделом "Обсуждения"