Общее описание API
Справочник по API
API – набор функций, помогающий понять, каким способом возможно обратиться к программе, включает в себя:
Операцию, которую можно выполнить
Данные, которые поступают на вход
Данные, которые оказываются на выходе (контент данных или сообщение об ошибке)
API продуктов VSaaS организован на основе REST.
REST API отвечает почти за все взаимодействия между серверными и клиентскими приложениями (серверное приложение дает доступ к своим данным клиентскому приложению по определенному URL).
API продукта VMS имеет предсказуемые URL-адреса, ориентированные на ресурсы, возвращает ответы в формате JSON, использует стандартные коды ответов HTTP, аутентификацию.
Все запросы должны иметь заголовок: Accept: application/json
Это необходимо для того, чтобы backend понимал, поддерживает ли клиент ответы в формате json. Если этого заголовка не будет, то ошибки будут возвращаться html-страницей.
Аутентификация
Аутентификация в API выполняется через bearer token. Его необходимо прислать в заголовке Authorization
. Пример: Authorization: Bearer eyJ0eXAiSUzI1NiJ9.eyJhdWQi.MHbBUJNRGEl2giGXN3uE
Запросы, на которых есть аутентификация, но не был предоставлен token или он неверный завершаться ошибкой со статусом 401.
Мультиязычность
VMS поддерживает мультиязычность (русский и английский язык). Чтоб изменить язык получаемых ответов, например ошибки или ресурсы, необходимо прислать заголовок Hl
или в запросе параметр hl
.
Пример
В заголовке - Hl: en
В GET
параметре - http://localhost/api/v1/items?hl=en
Ошибки
VMS использует обычные коды ответа HTTP, чтобы указать успешность или неудачу запроса API. В общем: коды в диапазоне 2xx указывают на успех. Коды в диапазоне 4xx указывают на ошибку запроса, который не удался с учетом предоставленной информации (например, не был указан обязательный параметр). Коды в диапазоне 5xx указывают на технические ошибки, в основном связанные с серверами VSaaS (они встречаются редко).
Пример ответа c 4xx статусом
{
"message": "The given data was invalid.",
"errors": {
"title": [
"The title field is required."
]
}
}
Список HTTP кодов и их значение
200, 201, 204 - OK | Процесс успешно сработал. |
---|---|
400 - Bad Request | Не удалось завершить запрос. Зачастую это связано с некорректной работой внешних систем. |
401 - Unauthorized | Указан неверный token API. |
402 - Payment Required | Превышен лимит лицензий на создание камер или существует проблема с лицензией. |
422 - Unprocessable Entity | Указанные в запросе данные неверны. |
403 - Forbidden | У API token нет разрешений на выполнение запроса. |
404 - Not Found | Запрошенный ресурс не существует. |
429 - Too Many Requests | Слишком много запросов попадает в API слишком быстро. |
500, 502, - Server Errors | Что-то пошло не так на стороне VSaaS (редко). |
503 - Service unavailable | Технические работы. Происходит происходит обновление системы или устранение неполадок. |
Пагинация
Все ресурсы API поддерживают массовую выборку с помощью методов API «list». Эти методы API имеют общую структуру, принимая по крайней мере два параметра: page
и per_page
{
"data": [
{...}
],
"links": {
"first": "https://localhost/url?page=1",
"last": "https://localhost/url?page=4",
"prev": null,
"next": "https://localhost/url?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"to": 25,
"last_page": 4,
"path": "https://localhost/url",
"per_page": 25,
"total": 86
}
}
Формат ответа:
data – массив запрашиваемых объектов
links (все ссылки в этом объекте содержат в
GET
параметрах данные, которые были присланы для фильтрации/сортировки на этот запрос):first – ссылка на первую страницу
last – ссылка на последнюю страницу
prev – ссылка на предыдущую страницу
next – ссылка на следующую страницу
meta:
current_page – номер текущей страницы
from – номер элемента с которого начинается эта страница
to – номер элемента на котором заканчивается эта страница
last_page – номер последней страницы
path – url по которому был запрос без всех параметров
per_page – количество элементов одной страницы
total – общее количество элементов, которое соответствует запросу