Skip to main content
Skip table of contents

Принципы работы с API VMS

Общая информация по API VMS

API (Application Programming Interface) — это набор функций, которые позволяют различным программным приложениям взаимодействовать друг с другом. API определяет, как приложения могут запрашивать и получать данные, а также выполнять определенные действия. Он включает в себя:

  • Выполняемые операции (методы) – набор действий или задач, которые приложение может осуществлять через API.

  • Входные данные (запросы) – данные, которые приложение передает в API для выполнения определенной операции. Они могут иметь форму параметров, аргументов или структур данных.

  • Выходные данные (ответы) – это информация, которую API отправляет обратно приложению в ответ на его запрос. Они включают в себя формат и структуру этих данных. Ответы могут содержать запрошенную информацию, подтверждение статуса выполненной операции или детализированные сообщения об ошибках.

API продуктов VSaaS организован на основе REST.

API продукта VMS соответствует следующим принципам REST:

  • Аутентификация: Требует аутентификацию для доступа к ресурсам.

  • JSON: Возвращает данные в стандартном формате JSON.

  • Стандартные коды HTTP: Применяет стандартные коды ответов HTTP для индикации статуса запроса.

Аутентификация и доступ к API

VMS API предоставляет два основных типа запросов: публичные (без аутентификации) и приватные (с использованием Bearer-токена).

  • Для публичных API-запросов не требуется аутентификация с использованием Bearer-токена. API для интеграции относится к публичным запросам.

  • Для доступа к приватным API-запросам требуется обязательная аутентификация. В качестве механизма аутентификации используется схема Bearer token. Такой вид аутентификации используется для работы с приватными API-запросами в VMS Admin API и VMS Client API. API для интеграции не использует Bearer-токен и относится к публичным запросам.

Для безопасности и контроля доступа к API используется белый список IP-адресов. Детали ниже в разделе «Управление доступом к API через IP-адрес».

Принцип работы использования Bearer token

Получение токена: Bearer-токен получается в результате отправки POST-запроса на эндпоинт /token.

Использование токена: При каждом запросе к защищенным ресурсам API необходимо использовать полученный ранее Bearer-токен в специальном HTTP-заголовке Authorization. Значение заголовка должно соответствовать следующему формату:

Authorization: Bearer <токен>

Где <токен> – это полученный вами Bearer-токен.

Пример использования токена в заголовке запроса:

Authorization: Bearer eyJ0eXAiSUzI1NiJ9.eyJhdWQi.MHbBUJNRGEl2giGXN3uE

Проверка токена: Серверная часть API проверяет валидность предоставленного токена. В случае успешной проверки сервер разрешает выполнение запрошенной операции.

Обработка ошибок аутентификации:

Ошибка 401 Unauthorized: Если при выполнении запроса к API, требующему аутентификации, заголовок Authorization отсутствует или предоставленный Bearer-токен является недействительным, сервер API возвращает ошибку со статусом 401 Unauthorized. В этом случае необходимо убедиться в наличии и корректности вашего Bearer-токена и повторить запрос с верными данными.

Ошибка 403 Forbidden: Сервер API может вернуть ошибку со статусом 403 Forbidden, если у пользователя отсутствуют необходимые разрешения для выполнения запрашиваемой операции, даже при наличии валидного Bearer-токена.

Управление доступом к API через IP-адрес

Для обеспечения безопасности и ограничения доступа к API используется механизм белого списка IP-адресов. Администраторы могут управлять этим списком с помощью Artisan команды ip-access:manage. Эта команда предоставляет инструменты для добавления, просмотра и очистки IP-адресов или подсетей, разрешенных для различных типов доступа к API.

Синтаксис команды:
php artisan ip-access:manage {type} {ip?} {--fresh} {--show}
Где:

  • {type} – обязательный аргумент, определяющий тип доступа, для которого осуществляется управление белым списком. Допустимые значения определены в константе App\Models\IpAccess::TYPES и включают:

    • admin

    • push1st

    • orchestrator

    • ib

    • integration_module

    • billing

    • analytic_video

  • {ip?} – опциональный аргумент, представляющий IP-адрес или подсеть, которую необходимо добавить в белый список. Подсеть указывается в формате IP/маска (например, 192.168.1.0/24). Если этот аргумент не указан, команда не будет добавлять новый IP-адрес.

  • --fresh – опциональный флаг. При его использовании текущий белый список для указанного типа доступа будет полностью очищен перед добавлением нового IP-адреса (если он указан).

  • --show – опциональный флаг. При его использовании отображается текущий белый список IP-адресов и подсетей, настроенных для указанного типа доступа. 

Примеры использования

  • Просмотр белого списка для типа billing:
    php artisan ip-access:manage billing --show

  • Добавление IP-адреса 192.168.1.100 для типа billing:
    php artisan ip-access:manage billing 192.168.1.100

  • Добавление подсети 192.168.1.0/24 для типа billing с очисткой списка:
    php artisan ip-access:manage billing 192.168.1.0/24 --fresh

Принцип работы

Применение команды ip-access:manage позволяет администраторам точно контролировать, какие IP-адреса или диапазоны IP-адресов имеют право доступа к защищенным API-маршрутам. Механизм промежуточной проверки (middleware) защищает систему, проверяя IP-адрес входящего запроса по белому списку, предназначенному для данного типа доступа.

При попытке доступа к защищенному API-маршруту с IP-адреса, отсутствующего в белом списке для требуемого типа доступа, сервер вернет ошибку HTTP с кодом 403 Forbidden, указывая на отсутствие разрешения на доступ к ресурсу

HTTP-заголовки в API-запросе играют важную роль в определении того, как API обрабатывает запросы и формирует ответы.

Заголовки запроса

Обязательный заголовок

Для обеспечения корректного взаимодействия с API и обработки ответов в ожидаемом формате, абсолютно каждый API-запрос должен содержать HTTP-заголовок Accept со значением application/json.

Accept: application/json

Такой заголовок необходим для того, чтобы сервер (backend) понимал, поддерживает ли клиент ответы в формате JSON. Это гарантирует, что сервер будет возвращать все данные, включая сообщения об ошибках, именно в формате JSON.

Отсутствие данного заголовка может привести к тому, что сервер, не имея явного указания на предпочтительный формат, может вернуть ответ в другом формате (например, HTML) даже при возникновении ошибок.

Дополнительные заголовки

Для специфических задач в VMS API существуют определенные заголовки, которые необходимо использовать дополнительно. Подробную информацию об этих заголовках вы найдете на соответствующих страницах документации по каждому разделу.

Настройка языка получаемых данных

API VMS предоставляет гибкую возможность адаптации языка возвращаемых данных в соответствии с вашими потребностями.

Для управления языком отображаемой информации, включая сообщения об ошибках и другие ресурсы, предусмотрен специальный языковой параметр hl, который используется для каждого запроса по отдельности

Существует следующие способы указания желаемого языка:

  • В запросе прислать заголовок hl c нужной локализацией. Например: Hl: en

  • В теле запроса или query params прислать поле hl. Вы можете передать параметр hl непосредственно в строке URL-запроса. Например: в GET параметре – https://your.domain/api/v1/items?hl=en.

Если вы передадите поле hl одновременно и в теле запроса (или query params), и в HTTP-заголовке запроса, то значение, указанное в заголовке, будет иметь приоритет.

  • Если не использовать варианты, указанные выше, то локализация устанавливается по умолчанию. Получить список доступных языков можно из запроса в параметре available_locales.

Валидация. Статусы обработки запроса

VMS использует стандартные коды ответа HTTP для обозначения успешного ответа на запрос или запроса с ошибкой. В этом разделе документации разработчики могут найти описание стандартных кодов ответов HTTP, которые используются VMS API для информирования о статусе обработки запросов.

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

При успешном завершении запроса сервер передает клиенту статус OK с кодом, находящимся в диапазоне 2xx.

В случае возникновения ошибки в процессе выполнения операции сервер передает сообщение, содержащее описание ошибки, а также соответствующий код из диапазонов 4хх и 5хх.

Коды в диапазоне 2xx

Указывают на успешное выполнение запроса.

200, 201, 204 – OK

Успешное выполнение запроса.

Коды в диапазоне 4xx

Указывают на ошибку запроса, который не удалось выполнить из-за ошибки в самом запросе, связанной с предоставленной информацией (например, пропущен обязательный параметр).

400 – Bad Request

Не удалось завершить запрос. Зачастую это связано с некорректной работой внешних систем. Запрос некорректный.

401 – Unauthorized

Указан неверный токен API. Запрос требует аутентификации.

402 – Payment Required

Превышен лимит лицензий на создание камер или возникла другая проблема с лицензированием.

422 – Unprocessable Entity

Указанные в запросе данные неверны.

403 – Forbidden

У токена API нет разрешений на выполнение запроса.

404 – Not Found

Запрошенный ресурс не существует.

429 – Too Many Requests

Отправляется слишком много запросов к API за короткий промежуток времени.

Коды в диапазоне 5xx

Указывают на технические ошибки, встречаются редко. В основном, такие ошибки связанные с серверами VSaaS.

500, 502 – Server Errors

Редко. Ошибки на стороне сервера VSaaS.

503 – Service unavailable

Технические работы. Происходит обновление системы или устранение неполадок.

Валидация запроса с ошибкой

При обнаружении ошибки в процессе выполнения операции, сервер отправляет клиенту сообщение, содержащее детали этой ошибки, а также соответствующий HTTP-код состояния в диапазонах 400-499 (клиентские ошибки) или 500-599 (серверные ошибки).

В большинстве случаев API возвращает сообщение об ошибке в следующем формате. Однако API может возвращать ошибки и в других структурах в зависимости от запроса.

CODE 
{
    "message": "Сообщение отсутствует",
    "errors": {
        "any_key": [
            "Детальная информация об ошибке"
        ]
    }
}

  • объект message – обычно представляет собой пустой объект и не содержит деталей ошибки. В некоторых случаях (например, при коде ошибки 400) это поле может включать описание ошибки.

  • объектerrors – предоставляет детальную информацию об ошибках, возникших при обработке запроса. Ключи в структуре errors указывают на поля запроса, вызвавшие ошибки. Важно отметить, что ошибки также могут возникать вне контекста конкретного поля. Объект errors может содержать несколько ошибок.

ПРИМЕР

Запрос содержит поле url со значением http//example.com. Для данного поля определено правило валидации, согласно которому оно должно представлять собой корректный URL-адрес и не превышать 10 символов в длину. Также в запросе присутствует поле date со значением 2000-01-01, которое должно соответствовать формату Y-m-d H:i:s.

Ответ на запрос с ошибкой будет выглядеть следующим образом:

JSON 
{
    "message": "Предоставлены неверные данные",
    "errors": {
        "url": [
            "Поле url имеет ошибочный формат.",
            "Поле url не может быть более 10 символов"
        ],
        "date": [
            "Поле date не соответствует формату Y-m-d H:i:s."
        ]
    }
}

Пагинация

Все ресурсы API поддерживают массовую выборку с помощью методов API list. Эти методы API имеют общую структуру, принимая как минимум два параметра – page и per_page.

Для всех ресурсов API доступна массовая выборка через методы list, которые характеризуются общей структурой и обязательным наличием параметров page и per_page.

Пример ответа

JSON 
{
    "data": [
        {...}
    ],
    "links": {
        "first": "https://your.domain/url?page=1",
        "last": "https://your.domain/url?page=4",
        "prev": null,
        "next": "https://your.domain/url?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "to": 25,
        "last_page": 4,
        "path": "https://your.domain/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 – общее количество элементов, которое соответствует запросу.

JavaScript errors detected

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

If this problem persists, please contact our support.

Contact Support Close