К содержимому
← Вернуться в блог

Как описать контракт API: входные данные, ошибки и повтор запросов

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

Ниже — о том, как описать контракт API так, чтобы по нему можно было писать код, тесты и обработку ошибок без догадок. Все примеры в тексте гипотетические: это шаблон описания, а не выдержка из конкретного проекта.

Как описать контракт API: что входит в документ

Контракт — не список эндпоинтов. Список отвечает на вопрос «куда стучаться», контракт — на вопросы «что именно придёт», «что я получу в ответ» и «что делать, если что-то пошло не так». Один и тот же адрес может работать годами, но если поведение при ошибке не описано, клиенты начнут угадывать, а угадывание почти всегда расходится с реальностью.

Удобно держать в голове три слоя описания:

  • Адрес и метод. Путь, HTTP-метод, версия, требования к авторизации и обязательные заголовки.
  • Данные. Поля запроса и ответа: типы, обязательность, форматы, ограничения, значения по умолчанию.
  • Поведение. Коды ответов, структура ошибок, лимиты, идемпотентность, правила повтора.

Третий слой пропускают чаще всего — и именно он определяет, насколько спокойно интеграция переживёт сетевой сбой или очередной деплой. Заодно стоит договориться, в каком виде документ живёт: текстовое описание в репозитории, спецификация вроде OpenAPI, таблица в общей вики. Формат вторичен; важнее, что он один и обновляется вместе с кодом, а не через месяц после релиза.

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

Входные данные: что фиксировать в запросе

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

  1. Имя поля и место передачи: путь, query-параметр, заголовок или тело запроса.
  2. Тип данных: строка, число, логическое значение, массив, объект.
  3. Обязательность и поведение сервиса, если поле не передали.
  4. Формат и ограничения: длина, диапазон, набор допустимых значений, кодировка.
  5. Значение по умолчанию для необязательных полей.
  6. Пример корректного и пример некорректного значения.
  7. Влияние на результат: что изменится, если поле передать или не передать.

Седьмой пункт часто считают избыточным, но именно он превращает документ в инструкцию. Формулировка «поле comment — строка до 500 символов» отвечает на вопрос о формате, но не о том, попадёт ли комментарий в счёт, в письмо клиенту или никуда.

Обязательные, необязательные и условно обязательные поля

Двоичного деления «обязательно / необязательно» не хватает. Есть третий тип — условная обязательность: поле нужно только при определённом значении другого поля. Гипотетический пример: операция создаёт платёж, и при способе оплаты «карта» требуются последние четыре цифры номера, а при способе «банковский перевод» — номер счёта получателя. Пока правило не записано, клиент узнаёт о нём из ошибки на рабочем окружении.

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

Валидация и граничные случаи

Ещё один блок, который экономит споры, — договорённости на границах. Перечислим то, что чаще всего обсуждают уже после начала разработки.

  • Пробелы по краям. Обрезает ли сервис пробелы в строках или считает их частью значения.
  • Регистр. Важен ли он для идентификаторов, адресов электронной почты, служебных кодов.
  • Юникод и нормализация. Считаются ли визуально одинаковые строки одинаковыми и в каком виде текст хранится.
  • Длина. В символах или в байтах и что происходит при превышении.
  • Даты и время. Формат, часовой пояс, что означает дата без времени.
  • Числа. Целые или дробные; для денежных сумм — договорённость о единицах и точности.
  • Массивы. Допустимы ли дубликаты, важен ли порядок, есть ли ограничение на количество элементов.
  • Размер тела запроса. Лимит и код ответа при его превышении.

Это не придирки: каждое решение здесь влияет на то, будет ли повторная отправка того же запроса давать тот же результат.

Ответ и критерии успеха

Успех тоже нужно определить, иначе клиент будет считать успехом всё, что вернуло код из диапазона 2xx. Обычно этого достаточно, но есть нюансы, которые лучше проговорить заранее.

Во-первых, структура тела ответа: какие поля присутствуют гарантированно, какие могут быть пустыми, какие появились в новой версии. Если поле может отсутствовать, это пишется прямо, а не оставляется клиенту наедине с пустым значением.

Во-вторых, идентификаторы. Если операция создаёт объект, стоит зафиксировать, что именно возвращается — внутренний идентификатор, внешний номер — и можно ли по нему получить объект позже. Гипотетический сценарий: клиент создал заказ, не получил ответа из-за таймаута и не знает, создался ли заказ. Если в ответе нет ни идентификатора, ни способа найти объект по бизнес-ключу, различить «создалось» и «не создалось» невозможно.

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

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

И последнее — совместимость. Договорённость «в рамках версии мы не удаляем поля и не меняем их смысл» стоит написать текстом: она дешевле, чем разбор инцидента после релиза.

Ошибки: как описать их так, чтобы клиент знал, что делать

Ошибка — часть контракта, а не досадное дополнение к нему. Хорошее описание даёт клиенту три вещи: понять причину, решить, повторять ли запрос, и найти виноватого, если причина неясна.

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

Ниже — пример того, как категории ошибок соотносятся с реакцией клиента. Коды статусов приведены как распространённая конвенция; в конкретном сервисе их значения стоит зафиксировать в документе.

Категория Примеры статусов Повторять Что делает клиент
Ошибка в данных запроса 400, 422 Нет Исправляет поля, повтор бессмысленен
Проблема с доступом 401, 403 Нет Обновляет токен или уточняет права
Объект не найден 404 Нет Проверяет идентификатор и порядок операций
Конфликт состояния 409 Обычно нет Разрешает конфликт по описанному правилу
Слишком много запросов 429 Да, с задержкой Ждёт, учитывая рекомендованную паузу
Временная ошибка сервера 500, 502, 503, 504 Да, ограниченно Повторяет с нарастающей паузой, если операция безопасна
Обрыв или таймаут — Да, если операция идемпотентна Повторяет с тем же ключом идемпотентности

По каждой ошибке в документе стоит зафиксировать: при каком условии она возникает, какой машинный код возвращается, какое тело приходит, можно ли повторить запрос и что именно нужно изменить. Отдельно — что делать нельзя. Например, если при конфликте клиент начнёт менять идентификатор и создавать новый объект, вместо одной ошибки появится дубль.

Три вещи в описание ошибок лучше не тащить: трассировки стека, внутренние имена таблиц и сервисов, персональные данные в тексте сообщения. Первые две бесполезны клиенту и полезны тому, кто ищет уязвимости; третья — риск, который оценивается по правилам работы с персональными данными. Если есть сомнения, стоит свериться с официальными требованиями и внутренней политикой, а не решать на глаз.

И ещё одно: клиент не должен разбирать текст сообщения. Машинный код стабилен, текст — нет. Если различие между двумя причинами отказа важно для логики, оно должно быть в коде, а не в формулировке.

Повтор запросов: идемпотентность и ключи

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

По конвенции HTTP методы GET, PUT и DELETE считаются идемпотентными, а POST — нет. Это именно конвенция, а не автоматическая гарантия: важно, что делает конкретный сервис, и это нужно описать явно. Фраза «повторный POST создаст второй заказ» в документации экономит часы отладки.

Рабочий приём для неидемпотентных операций — ключ идемпотентности. Клиент генерирует уникальное значение и передаёт его с запросом; сервер запоминает ключ вместе с результатом. При повторе с тем же ключом сервис не выполняет операцию заново, а возвращает ранее сохранённый ответ. Договориться нужно о четырёх вещах.

  • Как передаётся ключ. Отдельный заголовок или поле тела — главное, чтобы это было одинаково для всех операций.
  • Кто генерирует. Обычно клиент, и тогда важно, чтобы ключ создавался один раз на бизнес-операцию, а не на каждую попытку.
  • Сколько живёт ключ. Окно хранения выбирается по смыслу операции; в документе фиксируется конкретное значение, а не предположение.
  • Что происходит при конфликте. Тот же ключ с другим телом — это ошибка; какой код при этом вернётся, лучше написать прямо.

Если ключ идемпотентности ввести нельзя, работает проверка по бизнес-ключу: например, по внешнему номеру заказа, который назначает клиент. Тогда сервис при повторе находит существующий объект и возвращает его вместо создания нового. Подробнее о том, как выстроить обмен данными так, чтобы дубли не появлялись на уровне архитектуры, — в статье как автоматизировать обмен данными через API и избежать дублей.

Политика повторов: кто, что и с какой паузой

Идемпотентность отвечает на вопрос «можно ли повторять». Политика повторов отвечает на «как именно». Её тоже стоит описать, иначе каждый клиент придумает свою.

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

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

Теперь про саму паузу. Распространённый подход — экспоненциальная задержка со случайной добавкой: например, 1 секунда, 2, 4, 8 — со случайным разбросом, чтобы десятки клиентов не ударили по сервису одновременно после сбоя. Числа здесь иллюстративные; конкретные значения согласуются под нагрузку и характер операций, но сам принцип стоит зафиксировать в документе.

Важнее количества попыток — общий дедлайн. Три повтора по десять секунд и три повтора по две минуты — разные сценарии для пользователя, который ждёт результат. Разумно описать предельное время операции целиком, а не только число попыток, и указать, что происходит по его истечении: ошибка, отложенная обработка или запись в очередь.

И последнее — наблюдаемость. Если клиент повторяет запрос, у всех попыток должен быть общий признак, по которому их можно связать в логах: ключ идемпотентности, идентификатор операции или идентификатор запроса. Без этого разбор инцидента превращается в поиск иголки в стоге.

Шаблон описания операции и чек-лист

Когда слои определены, остаётся собрать их в повторяемый шаблон. Удобный порядок разделов для одной операции: назначение и ограничения, запрос с полями и примерами, ответ с гарантиями, ошибки с реакцией клиента, правила повтора и идемпотентности, лимиты, ссылки на смежные операции.

Проверить готовность описания помогает короткий чек-лист.

  1. У каждого поля есть тип, обязательность, ограничения и пример.
  2. Описано поведение при отсутствии поля и при пустом значении.
  3. Зафиксированы формат дат, часовой пояс и правила для денежных сумм.
  4. Перечислены все коды ответа, включая ошибочные, с телом и условием возникновения.
  5. Указано, какие ошибки имеет смысл повторять, а какие нет.
  6. Описана идемпотентность операции и способ передать ключ.
  7. Согласованы лимиты: размер тела, количество элементов, частота запросов.
  8. Есть пример полного цикла: запрос, успешный ответ, ошибка, повтор.
  9. Указано, что считается совместимым изменением, а что требует новой версии.

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

Контракт не обязан быть длинным. Он обязан быть однозначным: два разработчика, прочитав описание независимо друг от друга, должны прийти к одинаковому коду обработки ошибки и одинаковому решению о повторе. Если это условие выполняется, документ работает — даже если в нём нет ни одной модной схемы.

Чем контракт API отличается от документации API?

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

Обязательно ли описывать контракт в формате OpenAPI?

Нет. Формат — вопрос удобства: спецификация помогает генерировать клиентов и проверять соответствие, но контракт спокойно живёт и в виде структурированного текста или таблицы. Важнее, чтобы описание было единственным источником правды, обновлялось вместе с кодом и содержало не только структуру данных, но и поведение: ошибки, лимиты, правила повтора.

Что вернуть, если повторный запрос пришёл с тем же ключом идемпотентности, но другим телом?

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

Какие ошибки имеет смысл повторять автоматически?

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

Сколько попыток повтора и какая задержка считаются нормой?

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

Нужно ли описывать ошибки, которые «не могут случиться»?

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