Skip to main content
Skip table of contents

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.