Как мы описываем требования к REST API для бэкенда в Confluence

Конспект статьи. Автор оригинала: Ирина Тикинева (Magnit Tech)

Шаблон требований к REST API, который использует команда системных аналитиков Magnit Tech. Описания в Swagger дублировали автогенерацию FastAPI, поэтому первичным стал шаблон в Confluence.

Учебный пример

Вымышленный сервис, где котики публикуют посты с фото: просмотр своих постов с фильтрами, поиском и сортировкой; публикация поста (изображение до 30 МБ, текст до 256 символов).

Структура описания метода

1. Назначение, полный URL, кто может вызывать.
2. Заголовки и параметры: тип, ограничения, значения по умолчанию, соответствие полю БД («таблица.поле»), пагинация, пример curl.
3. Сценарий обработки: валидация, авторизация, бизнес-ошибки, лимиты (429), логирование, ссылка на sequence.
4. Успешный ответ и ошибки с примерами JSON; текст для пользователя — в отдельном поле.
5. Таблица кодов ответа и сообщений для интерфейса.

Публикация поста

Заголовок ключа идемпотентности, чтобы повтор после обрыва связи не создавал дубль. Тело — multipart/form-data. Успех — 201 Created, ошибка формата — 400. Критичные ограничения проверяются и на бэкенде, а не только на фронте.

По словам автора, шаблон сократил время подготовки требований, повысил их полноту и снизил число багов.