Эндпоинт API: что это и как читать описание запросов

Эндпоинт (endpoint, конечная точка) — это конкретный адрес в API, к которому программа отправляет запрос, чтобы выполнить определённое действие. Если API — это меню ресторана, то эндпоинт — отдельная позиция в нём: «получить список заказов», «создать клиента», «отменить платёж». Обычно эндпоинт определяется сочетанием адреса и HTTP-метода.

Из чего состоит адрес

Возьмём условный пример: https://api.example.com/v1/orders/123?include=items

• https — протокол, всегда защищённый для рабочих API
• api.example.com — сервер, на котором работает API
• /v1 — версия API
• /orders — коллекция ресурсов, заказы
• /123 — конкретный заказ, параметр пути
• ?include=items — параметр запроса, дополнительная настройка ответа

Базовая часть адреса одинакова для всех эндпоинтов API, а путь меняется в зависимости от ресурса и действия.

Метод

Один и тот же адрес может означать разные эндпоинты в зависимости от метода. GET по адресу /orders вернёт список заказов, а POST по тому же адресу создаст новый заказ. Поэтому в документации эндпоинт всегда записывают вместе с методом: GET /orders, POST /orders, DELETE /orders/123.

Параметры

• Параметры пути — часть адреса, обычно идентификаторы: номер заказа, код клиента
• Параметры запроса — после знака вопроса: фильтры, сортировка, страница, количество записей
• Тело запроса — данные, которые передаются при создании и изменении, обычно в JSON
• Заголовки — служебная информация: ключ авторизации, формат данных, язык

В документации для каждого параметра указывают тип, обязательность и допустимые значения. Неправильный регистр или лишний символ в адресе приводит к ошибке «не найдено», поэтому адреса лучше копировать из документации, а не набирать вручную.

Ответ

Эндпоинт возвращает код статуса и тело ответа. Описание ответа в документации показывает, какие поля придут, в каком формате, какие из них могут отсутствовать. Отдельно описываются ответы при ошибках.

Версии

API развивается: добавляются поля, меняется логика. Чтобы не ломать существующие интеграции, изменения, несовместимые с прежним поведением, выпускают в новой версии — например, /v2. Старая версия продолжает работать какое-то время, а партнёров предупреждают о сроке её отключения. При разработке интеграции фиксируйте, с какой версией вы работаете. Подпишитесь на рассылку или страницу изменений поставщика, чтобы узнавать о выходе новых версий заранее.

Как читать описание эндпоинта

1. Что делает эндпоинт и какие права нужны
2. Метод и адрес
3. Обязательные параметры
4. Пример запроса — с него удобно начинать проверку
5. Пример успешного ответа
6. Возможные ошибки и что они означают
7. Ограничения: лимиты, размер выдачи, постраничность

Постраничная выдача

Эндпоинты, которые возвращают списки, редко отдают все записи сразу. Они выдают страницу и информацию о том, как получить следующую. Интеграция, которая читает только первую страницу, теряет данные — частая ошибка при первой загрузке клиентов или товаров.

Пример из практики

Интеграция интернет-магазина с учётной системой использует несколько эндпоинтов: GET /products для загрузки каталога, GET /stock для остатков, POST /orders для передачи заказов, GET /orders/номер для проверки статуса. Описав их список заранее, заказчик и разработчик договариваются о границах интеграции и могут оценить объём работ.

Совет заказчику

Попросите разработчика составить таблицу эндпоинтов, которые использует ваша интеграция: метод, адрес, назначение, частота вызова. Она пригодится при поддержке, смене подрядчика и обновлении внешней системы.