# API Design

> Определить или развить контракт API, события, webhook или пакетного интерфейса, включая наблюдаемую совместимость, повторные запросы и ошибки. Применять для решений об интерфейсе; реализация относится к backend-разработке, а исполняемые проверки контракта — к тестированию API.

- Skill: `fbakiyev/api-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add fbakiyev/api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fbakiyev/api-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: fbakiyev (https://skillmd.com/u/fbakiyev)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/fbakiyev/api-design

---


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

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

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

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

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

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

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

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

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

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