Смартроад RESTful API
Система предоставляет разработчикам RESTful API для взаимодействия с внешними системами.
В общем виде запрос внешней системы для получения вида сведений, посредством унифицированных методов HTTP, выглядит следующим образом:
URL_smartroad/api/integration/функция?login=user_login&password=user_password
В таблице ниже описаны параметры запроса
| Параметр | Тип параметра | Описание |
|---|---|---|
| URL_smartroad | строка | Адрес веб-сервера, к которому идет обращение |
| Функция | строка | Часть URL, которая указывает на конкретный ресурс или функцию API |
| login | строка | Учетные данные пользователя в Системе. Указывается логин пользователя |
| строка | Альтернативный способ авторизации. Может использоваться вместо параметра login. В значении может передаваться как адрес электронной почты пользователя, указанный в профиле при регистрации, так и логин для доступа в Систему | |
| password | строка | Пароль пользователя |
Функция, login и password являются обязательными параметрами
Кроме того, описание параметров запроса Функции
| Функция | Описание функции |
|---|---|
| stat | Данные статистики |
| events | Получение событий |
| status | Информации о состоянии оборудования |
| pvr | Сведения о зарегистрированных в зонах подсчета объектах |
| sensors | Информация о детекторах |
Типы контента
Смартроад использует формат JSON для всех запросов и ответов API. Типом содержимого запроса и ответа является application/json.
Аутентификация
Система поддерживает аутентификацию с помощью JWT. Вы можете получить токен с помощью вызова API. Этот токен будет использоваться для всех последующих вызовов API.
HTTP запросов
REST API Смартроад стремится использовать соответствующий HTTP-запрос для каждого действия.
- В основном для извлечения ресурсов используется метод
GET.
Методы POST, PATCH, DELETE, UPDATE, пока не используются, но они могут быть реализованы с учетом требований клиента.
Обработка ошибок
Система использует коды состояния HTTP для указания статуса вызовов API.
Код состояния HTTP возвращается в заголовке ответа.
Список кодов состояния HTTP:
- 200: Successfully
- 400: The request failed
- 401: Unauthorized
- 403: Forbidden
- 404: Resource Not Found
- 429: Too many requests
- 500: Internal Server Error
Описания некоторых возможных ошибок:
| Код | Тип ошибки | Описание |
|---|---|---|
| 400 | The request failed. - Missing parameter / название_параметра – при отсутствующем обязательном параметре в запросе - Syntax error – при допущенной синтаксической ошибке в запросе - Unknown parameter / название_параметра – при некорректном указании параметра или указании несуществующего параметра | Не удалось обработать запрос, так как он представлен в неправильном формате или является некорректным. Ошибка синтаксиса запроса, некорректное указание или отсутствие обязательного параметра |
| 401 | Unauthorized | Необходимые данные для проверки подлинности отсутствуют или не являются допустимыми для ресурса. Некорректные значения в параметрах авторизации запроса |
| 403 | Forbidden | Отказано в доступе к запрашиваемому ресурсу: - У пользователя отсутствуют необходимые разрешения. - Указано неверное значение sensor_id и/или project_id |
| 429 | Too many requests | Между запросами прошло меньше определенного времени. Клиентское приложение было отрегулировано, и ему не следует пытаться повторить запрос, пока не пройдет определенное время |
| 500 | Internal server error | При обработке запроса возникла внутренняя ошибка сервера. На сервере произошла внутренняя непредвиденная ошибка или аварийный отказ |
Ответ на ошибку
Если вызов API завершился неудачей, текст ответа будет содержать сообщение об ошибке. Сообщение об ошибке представляет собой объект JSON со следующей структурой:
{
"error": {
"status": 500,
"message": "Internal server error"
}
}
Взаимодействие с внешними системами
В Системе реализована передача данных во внешние системы через RESTful API в виде JSON сообщений по запросу внешней системы.
Сбор, обработка и отправка данных производится по следующему алгоритму:
- ДТ собирает данные транспортного потока
- Адаптер формирует пакеты данных для передачи в БД
- Ресурс получает запрос на предоставление информации от внешней системы
- Ресурс обрабатывает запрос, формирует и отправляет ответ на запрос
Ограничения
ООО "Сорб Инжиниринг" оставляет за собой право добавлять поля без предварительного уведомления с сохранением обратной совместимости. Пожалуйста, убедитесь, что ваше программное обеспечение способно обрабатывать информацию при наличии дополнительных полей, которые могут быть добавлены в будущем, без необходимости внесения изменений в код.