API

API для работы с сервисом позволяет автоматизировать управление и анализ данных.

API – это некий набор правил, с помощью которых приложение может взаимодействовать с другим приложением или компонентом. Прикладной интерфейс программирования (API) может возвращать данные в разных форматах, например в JSON, XML или в бинарном формате, но в своем REST API мы будем использовать JSON-формат, как наиболее удобный.

Принцип работы

Доступ происходит по протоколу HTTPS по базовому адресу https://riginform.ru/api/. Параметры большинства запросов можно передавать с помощью GET или POST параметров. Ответ содержит объект или массив объектов по стандарту JSON.

Перед началом работы с API требуется получить token для дальнейшей авторизации. Это делается следующим образом (приведены примеры использования GET параметров):

  • https://riginform.com/api/auth/start?login=[логин] - возвращает в ответ string, содержащий соль
  • https://riginform.com/api/auth/login?login=[логин]&salt=[соль]&response=[response] - возвращает в ответ string, содержащий token; псевдокод для вычисления response на PHP: md5($password.$salt."\n") (сумма md5 строки "пароль+соль+символ-перевода-строки")

Последний запрос возвращает string, в нем token, его нужно запомнить и использовать для последующей авторизации. Token утрачивает силу при смене пароля аккаунта.

Ответы API с HTTP кодом 200 обозначают успешное исполнение операции. Другие коды (больше 200) обозначают ошибку, при этом тело ответа содержит string с объяснением.

Кодировка результата — UTF-8.

Команды API и общие соглашения

Большинство команд API, таких как /list, возвращают внутренние структуры из базы данных, которые содержат сотни полей. Документировать их трудоемко, поэтому рекомендуем просто смотреть на вывод соответствующих команд и анализировать структуры данных по очевидным названиям полей.

Доступные на данный момент команды

https://riginform.com/api + адрес из списка ниже. Обязательный параметр каждой команды - token. Остальные параметры приведены после команды.

Авторизация

GET/auth/start
Параметр Значение Описание Тип параметра Тип данных
login (required) Имя пользователя query string

Возвращает соль для авторизации. Это первый этап идентификации пользователя. Затем соль используется во втором, окончательном этапе авторизации, в запросе /auth/login. Запрос не требует дополнительных параметров.

GET/auth/login
Параметр Значение Описание Тип параметра Тип данных
login (required) Имя пользователя query string
salt (required) Соль (см./auth/start) query string
response (required) Вычисленный хэш query string

Возвращает ключ доступа, с которым в дальнейшем будут осуществляться всё взаимодействие с API (параметр 'token'). Для вычисления значения параметра 'response' необходимо получить представленную в hex MD5-сумму от объединения строк пароля пользователя, полученной соли и символа переноса строки. Псевдокод операции: hex(md5(password + salt + '\n'))

Бригады

GET/rig/list
Параметр Значение Описание Тип параметра Тип данных
token (required) Ключ доступа query string
start_time Начало периода query timestamp
end_time Конец периода query timestamp
days Флаг списка дней в ответе query integer

Возвращает список бригад из архива за заданный период времени. Если период времени не задан, возвращается список за последние 30 дней. Если установить параметр days=1, то список будет содержать массив дней (timestamp), имеющихся в базе данных для каждой бригады.

GET/rig/archive
Параметр Значение Описание Тип параметра Тип данных
token (required) Ключ доступа query string
rig Код бригады query integer
data_type Тип данных query integer
start_time Начало периода query timestamp
end_time Конец периода query timestamp

Возвращает значения параметров из архива за заданный период времени. Если не задан конец периода, возвращаются данные за 24 часа.

GET/rig/online
Параметр Значение Описание Тип параметра Тип данных
token (required) Ключ доступа query string

Возвращает список бригад онлайн.

GET/rig/channels
Параметр Значение Описание Тип параметра Тип данных
token (required) Ключ доступа query string
id Индекс бригады query integer
info Флаг информации по каналам Ключ доступа query integer
timeout Таймаут ожидания данных query integer

Возвращает текущие значения каналов с прибора. Идентификатора прибора id можно взять из запроса /rig/online. Эти идентификаторы не меняются со временем. Если не указывать id или указать id=0, то будет отправлен широковещательных запрос всем приборам. В ответе данные всех приборов сразу присутствовать не будут, так как запрос отправляется напрямую в прибор, то из-за задержек данные будут поступать не сразу, но обязательно будут присутствовать в ответах следующих запросов. Можно управлять временем ожидания данных через параметр timeout (сек). Чем больше время ожидания, тем больше данных успеет поступить с приборов. По умолчанию запрос завершается, как только будет получены данные хотя бы с одного прибора. Флаг info позволяет включать в ответ расширенную информацию по каналам, тип канала, предельные и аварийные значения.

В настоящее время идет процесс наполнения/создания полной документации к API на основе http://swagger.io, где будет систематизирована вся доступная информация.