Общее описание 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 статусом

JSON

{
    "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

JSON

{
    "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 – общее количество элементов, которое соответствует запросу