От метафоры к проверяемому договору

API часто объясняют через официанта между гостем и кухней. Метафора показывает посредничество, но быстро перестаёт помогать. Она не отвечает, как назвать нужный объект, кто вправе его читать, что произойдёт при повторе заказа и чем отличается ошибка формата от временной недоступности. Для рабочего разговора полезнее считать API контрактом.

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

Ресурс, endpoint и операция

Сначала определите ресурс — предмет, которым управляет API: пользователь, статья, заказ, файл или событие. Endpoint соединяет базовый адрес, путь и иногда параметры. Например, условный путь /orders обращается к коллекции заказов, а /orders/123 — к конкретному объекту. Реальные пути всегда берите из документации; похожее название не гарантирует одинаковую семантику.

HTTP-метод выражает намерение. GET обычно читает представление, POST часто создаёт или запускает операцию, PUT заменяет определённый ресурс, PATCH частично меняет, DELETE удаляет. Это не магические правила интерфейса: контракт сервиса должен уточнить эффект, требования, идемпотентность и право. Нельзя заключать, что любой POST безопасно повторять или любой DELETE физически стирает данные.

Визуальная схема запроса, ответа и авторизации

Рассмотрим синтетический запрос на создание заказа. Он не принадлежит реальному поставщику, поэтому названия и значения иллюстрируют структуру, а не готовую интеграцию. Двигайтесь по схеме слева направо и задавайте вопрос на каждом шлюзе.

Этап

Что находится в обмене

Что проверяется

Результат

1. Клиент

Цель создать один заказ и локальный request_id

Достаточно ли данных и безопасен ли повтор

Собран запрос

2. Endpoint и метод

POST /orders

Существует ли операция в текущей версии API

Запрос направлен нужному ресурсу

3. Headers

Content-Type, Authorization, Idempotency-Key

Формат, действительность токена, scope, ключ повтора

Запрос допущен к разбору

4. Body

customer_id, items, currency

JSON syntax, schema и бизнес-правила

Получен валидный payload

5. Авторизация объекта

Клиент и customer_id

Можно ли этому клиенту создавать заказ для объекта

Действие разрешено или отклонено

6. Ответ

Status, headers, body с order_id либо problem details

Выполнен ли предметный эффект и что делать дальше

Успех, исправление, ожидание или остановка

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

URL указывает протокол, host и путь. Query parameters обычно уточняют выборку: страницу, фильтр, сортировку. Не помещайте секреты в query string: адрес может попасть в историю, proxy logs и аналитику. Path parameter идентифицирует конкретный ресурс, но сервер всё равно обязан проверить право текущего клиента на него.

Headers несут метаданные. Content-Type сообщает формат body; Accept может обозначить желаемый формат ответа; Authorization передаёт credential по схеме, которую задаёт сервис. Correlation или request ID помогает связать логи. Названия пользовательских headers и правила их повторения берите из документации, потому что промежуточные компоненты обрабатывают их по-разному.

Body содержит представление данных. JSON широко распространён, но фигурные скобки не делают объект корректным. Строка вместо числа может быть синтаксически валидной, но нарушать схему; существующий customer_id может принадлежать другому аккаунту; допустимая сумма может быть в неверной валюте. Проверка проходит слоями: синтаксис, schema, права и бизнес-правило.

JSON Schema и OpenAPI выполняют разные роли

JSON Schema описывает структуру экземпляра: типы, обязательные поля, допустимые значения и другие assertions. OpenAPI документирует API шире: paths, operations, parameters, request bodies, responses, security schemes и связанные schemas. Хорошая документация позволяет увидеть не только пример, но и формальное ожидание.

Пример без схемы опасно копировать как полный контракт. В нём могут отсутствовать необязательные поля, граничные значения и альтернативные ответы. Схема без текста тоже недостаточна: она не объяснит предметный смысл, происхождение значения и последствия операции. Читайте их вместе и проверяйте версию документа.

Аутентификация и авторизация — не одно действие

Аутентификация отвечает, кто или какое приложение предъявило credential. Авторизация отвечает, что ему разрешено. Access token обычно представляет ограниченный выданный доступ, а не пароль пользователя. Scopes задают класс полномочий, но API дополнительно проверяет право на конкретный объект и контекст операции.

Токен хранится на серверной стороне или в секретном хранилище интеграции. Не вставляйте его в публичный JavaScript, таблицу, скриншот или URL. Для приложения используйте предусмотренный OAuth flow; проверяйте срок, audience, redirect URI и отзыв. Запрашивайте минимальные scopes: чтение профиля не должно незаметно давать удаление всех данных.

Отдельный риск — Broken Object Level Authorization. Даже если /orders/123 существует и token действителен, сервер должен проверить принадлежность или роль. Последовательные ID нельзя считать защитой. Со стороны клиента не пытайтесь компенсировать отсутствующую серверную проверку: это дефект API, который требует исправления владельцем.

Как читать ответ

Status code сообщает класс результата, а body даёт детали. 2xx означает, что HTTP-запрос успешно обработан по контракту, но предметное состояние всё равно нужно прочитать: операция могла быть принята асинхронно. 4xx обычно требует изменить запрос или полномочия. 5xx указывает на проблему серверной стороны, но не гарантирует, что побочный эффект отсутствовал.

Сигнал

Обычное значение

Безопасная реакция

200 / 201

Ответ или созданный ресурс

Проверить ID, состояние и обязательные поля

202

Операция принята, но может завершиться позже

Использовать документированный status endpoint или событие

400 / 422

Формат или предметная валидация не пройдены

Исправить данные; не повторять тот же payload бесконечно

401 / 403

Нет действительной аутентификации или права

Проверить credential и scope; не расширять права вслепую

404

Ресурс не найден или скрыт политикой

Проверить ID, среду и доступ без перебора чужих объектов

429

Превышен лимит запросов

Уважать Retry-After и уменьшить скорость

5xx / timeout

Серверный или сетевой сбой; эффект может быть неопределён

Сверить состояние и повторять только по безопасному контракту

Problem Details даёт стандартный контейнер для type, title, status, detail и instance, который API может расширять. Не показывайте внутренний detail пользователю без фильтрации: он способен содержать технический контекст. Для автоматической ветки опирайтесь на документированный type или code, а не на свободный текст, который поставщик может перевести или изменить.

Rate limits, pagination и версии меняют реальный объём работы

Список из десяти объектов не доказывает, что API вернул всё. Найдите pagination: номер страницы, cursor или continuation token, размер и признак конца. Сортировка должна быть стабильной, а обновления во время обхода способны привести к пропускам или повторам. Для большой выгрузки проверьте bulk или export endpoint вместо тысяч одиночных вызовов.

Rate limit может зависеть от токена, приложения, endpoint или общего аккаунта. Сохраните headers лимита, если они документированы, ограничьте concurrency и задайте backoff. Версия API может находиться в URL, header или настройке аккаунта. Перед обновлением сравните schemas и ошибки на тестовом наборе; дата deprecation важнее визуального сходства примеров.

Повтор запроса зависит от предметного эффекта

GET обычно проектируется как безопасное чтение, но всё равно может быть дорогим и лимитированным. Для POST после timeout нельзя угадывать, создался ли объект. Используйте idempotency key, если API его поддерживает, или запрос состояния по вашему предметному ключу. Новый случайный ключ для каждого retry уничтожает смысл защиты от дубля.

Перед автоматическим повтором ответьте: операция идемпотентна по контракту? Сколько живёт ключ? Сравниваются ли параметры? Что вернёт повтор? Можно ли сначала прочитать результат? Если документация молчит, считайте состояние неопределённым и передавайте его в сверку или человеку, а не нажимайте «повторить» до зелёного статуса.

Как читать документацию API за один проход

  1. Назовите ресурс и конкретную операцию, не начинайте с ключа доступа.

  2. Проверьте базовый URL, среду, версию и endpoint.

  3. Выпишите method, path/query parameters, required headers и body schema.

  4. Найдите security scheme, OAuth flow, scopes и object-level rules.

  5. Перечислите success responses, ошибки и машиночитаемые error codes.

  6. Проверьте pagination, filters, sorting, rate limits и concurrency.

  7. Отдельно найдите idempotency, retries, webhooks и status endpoint.

  8. Уточните deprecation policy, changelog, sandbox и поддержку.

Практический следующий шаг

Откройте документацию одного API, который планируете использовать, и заполните схему из шести этапов для ровно одной операции. Не создавайте реальный объект: выберите read-only endpoint или sandbox. Запишите точный URL без секрета, метод, параметры, scopes, успешный status, две ошибки, pagination и правило повтора. Если хотя бы одно высокозначимое поле нельзя подтвердить первичным документом, вынесите его как вопрос владельцу API до интеграции.

  • Ресурс, endpoint, method и версия выписаны из документации.

  • Path, query, headers и body не смешиваются.

  • JSON example проверен против schema.

  • Authentication, scopes и право на объект разделены.

  • Success, 4xx, 429, 5xx и timeout имеют разные реакции.

  • Pagination и rate limits учтены в полном объёме.

  • Изменяющий запрос повторяется только по идемпотентному контракту.

  • Токен хранится вне URL, клиентского интерфейса и журналов.

Что читать дальше