Общее описание API

Справочник по API

API (Application Programming Interface) — это набор функций, которые позволяют различным программным приложениям взаимодействовать друг с другом. 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: en

В GET параметре – http://localhost/api/v1/items?hl=en

Примеры ответов на запрос

VMS использует стандартные коды ответа HTTP для обозначения успешного ответа на запрос или запроса с ошибкой API.

Список HTTP кодов и их значение

Коды в диапазоне 2xx	Указывают на успешное выполнение запроса.
200, 201, 204 – OK	Успешное выполнение запроса.
Коды в диапазоне 4xx	Указывают на ошибку запроса, который не удался с учетом предоставленной информации (например, не был указан обязательный параметр).
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 за короткий промежуток времени.
Коды в диапазоне 5xx	Указывают на технические ошибки, встречаются редко. В основном, такие ошибки связанные с серверами VSaaS.
500, 502 – Server Errors	Редко. Ошибки на стороне сервера VSaaS.
503 – Service unavailable	Технические работы. Происходит обновление системы или устранение неполадок.

Пример ответа со статусом 4xx:

JSON

{
    "message": "The given data was invalid.",
    "errors": {
        "title": [
            "The title field is required."
        ]
    }
}

Пагинация

Все ресурсы 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 – объект, содержащий ссылки для пагинации результатов. Ссылки в объекте links формируются на основе параметров запроса (фильтров и сортировки):
- first – URL для получения первой страницы результатов.
- last – URL для получения последней страницы результатов.
- prev – URL для получения предыдущей страницы результатов.
- next – URL для получения следующей страницы результатов.
meta
- current_page – номер текущей страницы.
- from – номер элемента, с которого начинается данная страница.
- to – номер элемента, на котором заканчивается данная страница.
- last_page – номер последней страницы.
- path – URL, по которому был запрос без параметров.
- per_page – количество элементов одной страницы.
- total – общее количество элементов, которое соответствует запросу.