REST API для разработчиков

API Центрального пульта относится к категории REpresentational State Transfer (REST). Это значит, что возможно выполнять RESTful-операции на добавление, чтение, изменение и удаление информации для облачной учетной записи или инсталляции на сервере.

Описания методов можно найти здесь: https://api.saymon.tech/

Возможности REST API

Любые операции или действия, доступные в web-интерфейсе системы, могут быть реализованы с помощью API, например:

и многое другое.

Доступные API-методы

API-платформы реализованы как "JSON over HTTP" и предоставляют возможность использовать следующие методы:

Метод Назначение

GET

Получение данных о существующих объектах

POST

Создание новых объектов

PUT

Обновление и изменение существующих объектов

PATCH

Обновление и изменение существующих объектов

DELETE

Удаление существующих объектов

Права на выполнение операций

Доступ к данным и возможность выполнения тех или иных операций зависят от соответствующих прав учётной записи пользователя.

Аутентификация

Есть несколько способов, которые можно использовать для аутентификации при работе с API системы.

Basic Access Authorization

Базовая аутентификация может быть использована для получения данных об учётной записи следующим образом:

$curl -v -u login:password -H "Content-Type: application/json" -X GET https://your.server.name/node/api/users/current

где:

  • login – логин учётной записи,

  • password – пароль,

  • your.server.name – адрес сервера.

Session ID (Cookie)

Система позволяет сохранять идентификатор сессии, например в cookie, и использовать его в последующих запросах:

curl
$curl -v --cookie-jar cookies.txt -H "Content-Type: application/json" -X POST --data '{"login": "login", "password": "password"}' https://your.server.name/node/api/users/session
curl -v --cookie cookies.txt -H "Content-Type: application/json" -X GET https://your.server.name/node/api/users/current
ajax
$.ajax
({
  type: "POST",
  url: "https://your.server.name/node/api/users/session",
  dataType: 'json',
  async: true,
  data:
  {
    "login": "login",
    "password": "password"
  },
  success: function (res){
    console.log('Thanks for your login!');
    console.log('Session ID:'+res);
  },
  error: function () {
    console.log('Login failed!');
  }
});

где:

  • login – логин учётной записи,

  • password – пароль,

  • your.server.name – адрес сервера.

API Key (API Token)

Для получения API-токена необходимо:

  1. Войти в web-интерфейс системы.

  2. Нажать кнопку с именем учётной записи в правом верхнем углу.

  3. Открыть окно конфигурации системы.

API-токен будет указан в поле Ссылка для авторизации: https://your.server.name/?auth-token=52cc80e1-e2d8-4cff-a242-dfcfb538b585.

Его можно использовать в каждом запросе:

$curl -v -H "Content-Type: application/json" -X GET https://your.server.name/node/api/users/current?api-token=52cc80e1-e2d8-4cff-a242-dfcfb538b585

где:

  • your.server.name – адрес сервера.