Термины и определения Macroscop REST API🔗
Ниже приведены принятые в документации обозначения различных сущностей и компонентов Macroscop REST API.
Для примера рассматривается запрос
GET https://vms-server.mycompany.com/configuration/servers/1234-5678-9abc-def0
Фактический запрос (HTTP.HTTPS-запрос)🔗
Пример: GET https://vms-server.mycompany.com/configuration/servers/1234-5678-9abc-def0 с метаданными, заголовком, параметрами запроса.
Сформированное клиентом (браузером или приложением) сообщение, готовое к отправке на сервер.
Сессия (Цикл Запрос-Ответ)🔗
завершенная транзакция между клиентом и сервером, включающая в себя отправленный запрос и полученный от сервера результат (HTTP-ответ со статус-кодом, заголовками и телом).
Метод (HTTP-метод)🔗
GET, POST, PUT, DELETE. Указывает серверу, какое действие нужно совершить над ресурсом.
Протокол (Схема)🔗
http:// или https://
Хост🔗
Примеры: vms-server.mycompany.com или 192.168.0.1
Сетевой адрес сервера, обрабатывающего клиентские запросы: доменное имя или IP-адрес.
Путь (Шаблон пути)🔗
Пример: /configuration/servers/{server_id}
Относительный адрес в системе, который описывает иерархию ресурсов.
Эндпойнт (Операция, Маршрут)🔗
Пример: GET /configuration/servers/{server_id}
Уникальный идентификатор конкретного действия в API. Состоит из двух обязательных компонентов: HTTP-метода и пути.
Базовый путь (Префикс пути)🔗
Пример: /configuration/
Используется для группировки эндпоинтов (например, всё, что связано с конфигурацией, начинается с /configuration/).
Коллекция🔗
Пример: /configuration/servers/
Часть пути, указывающий на список ресурсов
Параметр пути🔗
Пример: {server_id}
Динамическая переменная (плейсхолдер) внутри URL. Заменяется на реальный идентификатор конкретного объекта при фактическом вызове API.
Ресурс (URL)🔗
Пример: /1234-5678-9abc-def0
Конкретный объект. В примере: сервер с идентификатором 1234-5678-9abc-def0 в коллекции серверов системы видеонаблюдения.
URL (URI)🔗
Пример: https://vms-server.mycompany.com/configuration/servers/1234-5678-9abc-def0
Указатель на ресурс.
Параметры строки запроса🔗
Пример: GET /configuration/servers/{server_id}?user=root&pass=
Здесь ?user=root&pass=. В отличие от параметра пути, не меняют сам ресурс, а лишь уточняют детали запроса.