Nemagu Документирование HTTP API
Описывать наблюдаемый HTTP-контракт независимо от фреймворка и языка реализации.
Обязательные справочники
Перед созданием или ревью читать:
- structure.md — структура файлов и навигация;
- endpoint-contract.md — нормативное содержание endpoint-а и моделей;
- review-checklist.md — проверка готовности.
Размещение и навигация
Размещать HTTP-документацию внутри presentation/http/ принятой структуры.
Внутреннюю иерархию областей, версий, ресурсов, endpoint-ов и моделей определяет
этот скил. Не создавать отдельный корневой external-contracts/http.
Формировать только фрагмент SUMMARY.md, начинающийся с «HTTP API». Главный скил
встраивает его внутрь «Презентационного слоя»; HTTP-скил не переставляет корневые
архитектурные разделы.
Архитектурная граница
Стабильные обозначения
Использовать схему
<контекст>.presentation.http.<область>.<версия>.<ресурсы>.<действие или модель>.
Область, версия, ресурс и действие являются отдельными смысловыми сегментами; не
склеивать ресурс с действием и не пропускать ресурс. Одинаковый endpoint или
модель во всей документации имеет одно обозначение независимо от имени файла.
Presentation вызывает публичную application-операцию. HTTP-модели принадлежат presentation и не являются командами, запросами или DTO application. Сопоставлять только публичные application-исходы; не интерпретировать domain-ошибки напрямую.
Код не считать источником требований. При адаптации существующей документации читать код только после отдельного разрешения пользователя и только для разрешения названного расхождения.
Рабочий процесс
- Согласовать область доступности, версию, базовый адрес, аутентификацию, формат содержимого, общие ошибки и политику ответов команд.
- Определить ресурсы и их границы.
- Связать каждый endpoint с одной публичной application-операцией.
- Описать каждый источник входа и отдельные HTTP-модели.
- Описать поле за полем валидацию и преобразование в application-вход.
- Описать успешный результат, заголовки и преобразование результата.
- Сослаться на общие ошибки и зафиксировать только отклонения endpoint-а.
- Определить повтор, совместимость и стабильное обозначение.
- Добавить минимальные примеры, не расширяющие нормативные таблицы.
- Обновить навигацию и выполнить checklist.
До массового описания однотипных ресурсов полностью проработать один эталонный ресурс и согласовать его с пользователем.
Согласование решений
Не выбирать самостоятельно метод, адрес, статус создания, Location, каноничный
завершающий /, правила null, неизвестных полей, сортировки или совместимости.
Предлагать варианты и фиксировать выбранное решение глобально, если оно общее.
За один подход задавать до пяти коротких, до трёх средних либо один-два крупных связанных вопроса. Не повторять глобальные вопросы для каждого ресурса.
Политика минимальных ответов
Предлагать как согласуемый вариант:
GETвозвращает запрошенные данные;- создание возвращает только идентификатор созданного агрегата;
- изменение, удаление и восстановление возвращают
204 No Content; - актуальное состояние клиент получает отдельным
GET.
Статус создания и заголовок Location согласовывать отдельно. Не считать их
автоматическим следствием этой политики.
Готовность
Документ готов, если реализация не требует выбирать адресацию, источник или
представление значения, обязательность, null и пустое значение, валидацию,
преобразование, сортировку, пагинацию, статусы, заголовки, тело, повтор или
совместимость.
Каждый содержательный документ завершать разделом ## Открытые вопросы. Если
вопросов нет, писать Открытых вопросов нет.. Не писать это, пока сохраняется
неявно выбранное решение.