API Design

Проектирование API

Определить границу

Установи поставщиков и потребителей данных, развёрнутые версии клиентов, принадлежность ресурсов, протокол и требуемое поведение. Изучи существующую схему и реальные предположения клиентов. Отличай предлагаемый контракт от уже реализованного поведения: неизвестные потребители ограничивают вывод о совместимости, а не доказывают безопасность изменения.

Решения по контракту

• Проверяй запросы и ответы отдельно. Новое обязательное поле запроса ломает старых клиентов; новое значение перечисления в ответе может сломать клиента с исчерпывающим разбором вариантов. Где это существенно, определи поведение для отсутствующего поля, null, значения по умолчанию и неизвестного поля вместо предположения, что любое добавление совместимо.
• Для повторяемой операции изменения определи область действия ключа, идентичность входных данных, ответ на повтор, повторное использование ключа с другими данными, срок хранения и обработку одновременных дубликатов. Укажи, какое устойчиво сохраняемое действие защищает ключ. Локальная запись дедупликации сама по себе не делает внешний побочный эффект атомарным.
• Различай отклонение до выполнения, известный неуспех выполнения и неизвестный исход после таймаута. Определи, как клиент сверяет результат или повторяет каждый случай, включая необходимые ограничения повторов. Одного HTTP-метода или статуса недостаточно для полного контракта повторных запросов.
• Для пагинации или доставки событий задай устойчивый порядок с дополнительным критерием для равных значений и то, что читатель может увидеть при вставке, удалении или повторном воспроизведении. Осознанно выбери семантику снимка или best-effort вместо одновременного обещания дешёвого чтения и безусловно согласованного снимка.
• Определи авторизацию для ресурса или операции, включая доступ между учётными записями. Детали ошибки должны помогать законному клиенту действовать, не раскрывая ему состояние чужих частных ресурсов. Сохраняй принятые идентификаторы ошибок и структуру ответов, если от них зависят клиенты.

Применяй только решения, относящиеся к изменяемому интерфейсу. Не вводи версионирование, новый протокол или полную спецификацию ради переименования внутренней вспомогательной функции.

Результат и проверка

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

Проверь примеры по схеме доступными средствами проекта. Рассмотри хотя бы один контрпример, отличающий новое поведение от прежнего дефекта; исполняемые проверки сервиса относятся к тестированию API, когда это запрошено. Непроверенную совместимость обозначай явно.

templates/api-contract.md необязателен и используется при доступном репозитории. Контракт можно подготовить в принятом проектном формате без этого шаблона.