API endpoint

Что такое API endpoint

Endpoint (эндпоинт, конечная точка) — адрес, по которому доступна одна конкретная операция API. Если API — это меню сервиса целиком, то эндпоинт — одна строка в меню.

Важная деталь: эндпоинт определяется не только URI, но и HTTP-методом. GET /v1/orders и POST /v1/orders — один адрес, но два разных эндпоинта: первый отдаёт список заказов, второй создаёт новый.

https://api.example.com/v1/orders/42
└──────┬──────────────┘└┬┘└───┬────┘
    базовый URL        версия  путь ресурса

Как это выглядит

curl -i -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sku": "GPU-4090", "qty": 1}'

Как называют эндпоинты

Соглашения REST, которых стоит держаться:

• Существительные, а не глаголы. POST /orders, а не /createOrder — действие уже выражено методом.
• Множественное число и вложенность. /users/42/orders — заказы конкретного пользователя.
• Версия в пути. /v1/... позволяет выпустить /v2/ и не сломать старых клиентов.
• Фильтры — в query-параметрах. /orders?status=paid&limit=50, а не отдельный эндпоинт под каждый фильтр.
• Постоянство. Опубликованный эндпоинт — обещание: у чужих клиентов он захардкожен, и переименование ломает их всех.

Полный список эндпоинтов сервиса перечислен в спецификации Swagger / OpenAPI — в разделе paths. Если документации нет, реальные вызовы видны во вкладке Network браузера и в HAR-файле.

Что не является эндпоинтом API

Слово «endpoint» встречается в двух других смыслах, и они не про API:

• В корпоративной ИБ endpoint — конечное устройство: ноутбук, телефон, рабочая станция. Отсюда endpoint security и EDR — защита рабочих мест, а не адресов.
• В сетях конечной точкой называют любую сторону соединения — например, endpoint VPN-туннеля.

Понять, о чём речь, помогает контекст: если рядом звучат «метод», «путь» или «запрос» — имеется в виду адрес API.

Эксплуатация

Эндпоинты одного сервиса нагружены очень по-разному: /healthz дёргают раз в секунду и он обязан отвечать мгновенно, а тяжёлый POST /v1/generate с инференсом занимает GPU на секунды. Отсюда практика разносить их: лёгкие и тяжёлые пути маршрутизируют на разные группы серверов через API Gateway или балансировщик, а лимиты частоты задают отдельно для каждого пути.

Связанные термины

• API — набор эндпоинтов сервиса
• URI и query-параметры — из чего состоит адрес
• HTTP — методы, задающие смысл вызова
• REST API — стиль, откуда пришли соглашения об именовании
• Swagger / OpenAPI — где смотреть список эндпоинтов
• API Gateway — маршрутизация запросов по эндпоинтам