Проектирование API
Проектирует интерфейс сервиса: методы, форматы запросов и ответов, коды ошибок и то, что обычно забывают.
Что делает
Проектирует интерфейс сервиса по описанию его задач: какие методы нужны, что приходит в запросе, что возвращается в ответе, какими кодами обозначаются ошибки. Отдельно проговариваются вещи, о которых обычно вспоминают позже, — постраничная выдача, версии, ограничение частоты обращений, повторная отправка одного и того же запроса.
Когда пригодится
Начинаете новый сервис, и нужен внятный черновик интерфейса до первой строки кода. Договариваетесь с соседней командой, что именно вы друг другу отдаёте. Интерфейс складывался стихийно, и нужно посмотреть, как он выглядел бы собранным. Нужно быстро прикинуть, во что выльется новая функция со стороны запросов.
Как заполнить
Что должен уметь сервис Опишите функции обычными словами, до 2500 знаков: кто пользуется сервисом, что он хранит, что с этим можно делать. Перечисление действий работает лучше абстрактного описания — «создать заказ, оплатить, отменить до отгрузки, посмотреть историю» даёт куда более точный результат, чем «сервис заказов». Упомяните и то, что важно для формата: большие списки, файлы, права доступа, внешние уведомления. Стиль Как устроен интерфейс: REST — привычные адреса и методы, самый распространённый вариант. GraphQL — один вход и запрос ровно тех полей, что нужны клиенту. RPC — вызовы именованных операций, ближе к обычным функциям. Не уверены — берите REST: под него больше всего готовых инструментов и примеров, и его проще передать другой команде.
Что получится
Текстовое описание интерфейса: список методов с назначением, форматы запросов и ответов с примерами полей, коды состояний и ошибок, замечания по сквозным вещам вроде разбивки на страницы и версионирования. Это проект, а не готовый код: спецификацию в машинном формате и реализацию нужно будет собирать отдельно, но спорить о структуре уже есть о чём.
