API
API для работы с сервисом позволяет автоматизировать управление и анализ данных.
API – это некий набор правил, с помощью которых приложение может взаимодействовать с другим приложением или компонентом. Прикладной интерфейс программирования (API) может возвращать данные в разных форматах, например в JSON, XML или в бинарном формате, но в своем REST API мы будем использовать JSON-формат, как наиболее удобный.
Принцип работы
Доступ происходит по протоколу HTTPS по базовому адресу https://riginform.com/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 | |
| format | Вид возвращаемых данных | query | integer | |
| caption | Флаг добавления названий | query | integer | |
| hash | Флаг добавления хеша данных | query | integer |
Возвращает список бригад из архива за заданный период времени. Если период времени не задан, возвращается список за последние 30 дней. Максимальная глубина списка (end_time-start_time) может быть не более 90 дней.
Параметр 'format' задает вид возвращаемых данных. format=0 – возвращается только список бригад; format=1 – возвращается список бригад и дней в древовидном виде; format=2 – возвращается список бригад и дней в табличном виде.
| GET | /rig/archive |
|---|
| Параметр | Значение | Описание | Тип параметра | Тип данных |
|---|---|---|---|---|
| token | (required) | Ключ доступа | query | string |
| rig | (required) | Код бригады | query | integer |
| data_type | (required) | Тип данных | query | integer |
| device | (required) | Серийный номер прибора | query | integer |
| start_time | (required) | Начало периода | query | timestamp |
| end_time | Конец периода | query | timestamp |
Возвращает значения параметров из архива за заданный период времени. Если не задан конец периода, возвращаются данные за 24 часа.
Параметры 'data_type' и 'device' необходимо получить из функции /rig/list.
| 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, где будет систематизирована вся доступная информация.