Как описать контракт API: входные данные, ошибки и повтор запросов
Интеграция редко ломается из-за сложной логики. Чаще — из-за того, что две команды по-разному поняли простое: какое поле обязательно, что означает пустая строка и можно ли повторить запрос, если ответ не пришёл. Контракт API фиксирует именно эти договорённости: что сервис принимает, что возвращает и как ведёт себя при сбоях.
Ниже — о том, как описать контракт API так, чтобы по нему можно было писать код, тесты и обработку ошибок без догадок. Все примеры в тексте гипотетические: это шаблон описания, а не выдержка из конкретного проекта.
Как описать контракт API: что входит в документ
Контракт — не список эндпоинтов. Список отвечает на вопрос «куда стучаться», контракт — на вопросы «что именно придёт», «что я получу в ответ» и «что делать, если что-то пошло не так». Один и тот же адрес может работать годами, но если поведение при ошибке не описано, клиенты начнут угадывать, а угадывание почти всегда расходится с реальностью.
Удобно держать в голове три слоя описания:
- Адрес и метод. Путь, HTTP-метод, версия, требования к авторизации и обязательные заголовки.
- Данные. Поля запроса и ответа: типы, обязательность, форматы, ограничения, значения по умолчанию.
- Поведение. Коды ответов, структура ошибок, лимиты, идемпотентность, правила повтора.
Третий слой пропускают чаще всего — и именно он определяет, насколько спокойно интеграция переживёт сетевой сбой или очередной деплой. Заодно стоит договориться, в каком виде документ живёт: текстовое описание в репозитории, спецификация вроде OpenAPI, таблица в общей вики. Формат вторичен; важнее, что он один и обновляется вместе с кодом, а не через месяц после релиза.
Полезно представить трёх читателей. Разработчик на стороне клиента ищет типы и примеры. Тестировщик — граничные случаи и коды ошибок. Поддержка — что означает конкретное сообщение в логах. Если документ отвечает только первому, остальные двое будут ходить с вопросами к авторам сервиса. Часть этих деталей пересекается с тем, что обычно попадает в задание на интеграцию: об этом есть отдельный разбор про ТЗ на API и фоновые задачи.
Входные данные: что фиксировать в запросе
Описание входа — самая механическая часть работы, и в ней же остаётся больше всего пробелов. Помогает простое правило: для каждого поля в документе должно быть семь ответов.
- Имя поля и место передачи: путь, query-параметр, заголовок или тело запроса.
- Тип данных: строка, число, логическое значение, массив, объект.
- Обязательность и поведение сервиса, если поле не передали.
- Формат и ограничения: длина, диапазон, набор допустимых значений, кодировка.
- Значение по умолчанию для необязательных полей.
- Пример корректного и пример некорректного значения.
- Влияние на результат: что изменится, если поле передать или не передать.
Седьмой пункт часто считают избыточным, но именно он превращает документ в инструкцию. Формулировка «поле 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 — со случайным разбросом, чтобы десятки клиентов не ударили по сервису одновременно после сбоя. Числа здесь иллюстративные; конкретные значения согласуются под нагрузку и характер операций, но сам принцип стоит зафиксировать в документе.
Важнее количества попыток — общий дедлайн. Три повтора по десять секунд и три повтора по две минуты — разные сценарии для пользователя, который ждёт результат. Разумно описать предельное время операции целиком, а не только число попыток, и указать, что происходит по его истечении: ошибка, отложенная обработка или запись в очередь.
И последнее — наблюдаемость. Если клиент повторяет запрос, у всех попыток должен быть общий признак, по которому их можно связать в логах: ключ идемпотентности, идентификатор операции или идентификатор запроса. Без этого разбор инцидента превращается в поиск иголки в стоге.
Шаблон описания операции и чек-лист
Когда слои определены, остаётся собрать их в повторяемый шаблон. Удобный порядок разделов для одной операции: назначение и ограничения, запрос с полями и примерами, ответ с гарантиями, ошибки с реакцией клиента, правила повтора и идемпотентности, лимиты, ссылки на смежные операции.
Проверить готовность описания помогает короткий чек-лист.
- У каждого поля есть тип, обязательность, ограничения и пример.
- Описано поведение при отсутствии поля и при пустом значении.
- Зафиксированы формат дат, часовой пояс и правила для денежных сумм.
- Перечислены все коды ответа, включая ошибочные, с телом и условием возникновения.
- Указано, какие ошибки имеет смысл повторять, а какие нет.
- Описана идемпотентность операции и способ передать ключ.
- Согласованы лимиты: размер тела, количество элементов, частота запросов.
- Есть пример полного цикла: запрос, успешный ответ, ошибка, повтор.
- Указано, что считается совместимым изменением, а что требует новой версии.
Совет. Перед согласованием контракта прогоните один реальный сценарий целиком, включая сбой: создание объекта, таймаут, повтор с тем же ключом и проверку, что объект остался один. Такой прогон на бумаге выявляет пробелы быстрее, чем чтение документа с начала до конца.
Контракт не обязан быть длинным. Он обязан быть однозначным: два разработчика, прочитав описание независимо друг от друга, должны прийти к одинаковому коду обработки ошибки и одинаковому решению о повторе. Если это условие выполняется, документ работает — даже если в нём нет ни одной модной схемы.
Чем контракт API отличается от документации API?
Документация описывает, как пользоваться сервисом: адреса, параметры, примеры. Контракт — это зафиксированные обязательства, которые считаются неизменными в рамках версии: какие поля обязательны, что означает пустое значение, какие коды возвращаются, можно ли повторять запрос и когда результат повтора совпадёт с первым. Документация может быть частью контракта, но сама по себе она не создаёт договорённостей, пока в ней не сказано, что именно гарантируется.
Обязательно ли описывать контракт в формате OpenAPI?
Нет. Формат — вопрос удобства: спецификация помогает генерировать клиентов и проверять соответствие, но контракт спокойно живёт и в виде структурированного текста или таблицы. Важнее, чтобы описание было единственным источником правды, обновлялось вместе с кодом и содержало не только структуру данных, но и поведение: ошибки, лимиты, правила повтора.
Что вернуть, если повторный запрос пришёл с тем же ключом идемпотентности, но другим телом?
Это конфликт, и его стоит описать заранее. Распространённый вариант — вернуть ошибку конфликта и не выполнять операцию: клиент должен либо использовать новый ключ, либо исправить тело запроса. Возвращать результат первого запроса в такой ситуации опасно, потому что клиент решит, будто применились новые данные. Конкретный код и тело ответа фиксируются в контракте.
Какие ошибки имеет смысл повторять автоматически?
Те, причиной которых стал временный сбой: обрыв соединения, таймаут, ответы о временной недоступности сервера и сообщения о превышении частоты запросов с рекомендацией подождать. Ошибки в данных, проблемы с доступом и конфликты состояний повторять бессмысленно — результат не изменится. Для неидемпотентных операций повтор допустим только при наличии ключа идемпотентности или проверки по бизнес-ключу.
Сколько попыток повтора и какая задержка считаются нормой?
Единого значения нет: параметры зависят от характера операции и допустимого времени ожидания. Практичнее описать не «магическое число», а принцип — нарастающая пауза со случайным разбросом, ограниченное число попыток и общий дедлайн операции. Эти значения согласуются между клиентом и сервисом и фиксируются в контракте.
Нужно ли описывать ошибки, которые «не могут случиться»?
Стоит описать хотя бы их категории. Внутренние сбои, перегрузка и ошибки конфигурации случаются независимо от качества кода, и клиенту нужно знать, как на них реагировать: повторять, показать сообщение или отложить операцию. Достаточно зафиксировать общий формат такой ошибки и правило поведения, без перечисления всех возможных причин.