Смартроад RESTful API 2.0

Система предоставляет разработчикам RESTful API для взаимодействия с внешними системами.

В общем виде запрос внешней системы для получения вида сведений посредством унифицированных методов HTTP выглядит следующим образом:

<url_smartroad>/api/<version>/<запрос>?login=<user_login>&password=<user_password>

Перечень всех запросов API

Запрос	Описание метода
login	Авторизация пользователя с помощью JWT токена
refresh	Обновление токена по истечению срока его действия
events	Получение событий
status	Информации о состоянии оборудования
stat	Данные статистики
sensors	Информация о детекторах
rate	Оценка транспортного потока по витрине статистики
jam	Оценка заторовой ситуации транспортного потока

Перечень параметров запроса

Параметр	Описание
url_smartroad	Адрес веб-сервера, к которому идёт обращение.
version	Версия API. Может быть указан как номер протокола (2.0), так и либо иной эндпоинт (например, integration) на усмотрение организации, использующей API.
метод	Метод API, к которому идёт обращение.
login	Логин пользователя в Системе.
password	Пароль пользователя.
username	Логин пользователя, используемый при авторизации с помощью метода login.
email	Почта пользователя.
sensorId	Уникальный идентификатор искомого детектора.
project_id	Уникальный идентификатор проекта, в котором находится искомый детектор.
sensorName	Имя искомого детектора. DEPRECATED - нежелательный параметр.
startDate / from	Начало временного периода.
endDate / to	Конец временного периода.

ОБРАТИТЕ ВНИМАНИЕ

Запрос, login и password являются обязательными параметрами

Методы HTTP запросов

RESTful API Смартроад стремится использовать соответствующий HTTP-запрос для каждого действия.

Запрос	HTTP метод
login	POST
refresh	POST
events	GET
status	GET
stat	GET
sensors	GET
rate	GET
jam	GET

ПРИНЯТЬ К СВЕДЕНИЮ

Методы PATCH, DELETE, UPDATE, пока не используются, но они могут быть реализованы с учетом требований клиента.

Обработка ошибок

Система использует коды состояния HTTP для указания статуса вызовов API. Код состояния HTTP возвращается в заголовке ответа.

Список кодов, которые пользователь может получить при отправке запросов Системе:

• 200: OK
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 429: Too many requests
• 500: Internal Server Error

Список общих ошибок для всех запросов:

Код ошибки	Описание/сообщение	Способ получения
400	API not found or disabled	Ошибки/опечатки в написании названия запроса, отправка несуществующего запроса
429	Too many requests	Между запросами прошло меньше определенного времени. Клиентское приложение было отрегулировано, и ему не следует пытаться повторить запрос, пока не пройдет определенное время
500	Internal server error	При обработке запроса возникла внутренняя ошибка сервера. На сервере произошла внутренняя непредвиденная ошибка или аварийный отказ

Взаимодействие с внешними системами

В Системе реализована передача данных во внешние системы через RESTful API в виде JSON сообщений по запросу внешней системы.

Схема взаимодействия с внешними системами.

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

1. ДТ собирает данные транспортного потока;
2. Адаптер формирует пакеты данных для передачи в БД;
3. Веб-сервер получает запрос на предоставление информации от внешней системы;
4. Веб-сервер обрабатывает запрос, с помощью PostgREST запрашивает и принимает требуемые данные из БД;
5. Веб-сервер формирует и отправляет ответ на запрос.

Ограничения

ООО Сорб Инжиниринг оставляет за собой право добавлять поля без предварительного уведомления с сохранением обратной совместимости. Пожалуйста, убедитесь, что ваше программное обеспечение способно обрабатывать информацию при наличии дополнительных полей, которые могут быть добавлены в будущем, без необходимости внесения изменений в код.