Разработка через спецификацию: сначала контракт API, потом код

Разработка через спецификацию — подход, при котором до написания кода команда описывает контракт API: какие есть ресурсы, какие запросы можно отправлять, какие поля и ошибки возвращаются. Спецификация становится единственным источником правды, по которому параллельно работают бэкенд, веб-интерфейс, мобильное приложение и партнёры по интеграции. Подход также называют API-first или contract-first.

Как обычно бывает без него

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

Как работает подход

1. Аналитик и разработчики вместе описывают спецификацию API по пользовательским сценариям.
2. Спецификацию обсуждают все потребители: веб, мобильное приложение, бот, партнёры.
3. После согласования по ней генерируется документация и тестовый сервер-заглушка, возвращающий примеры ответов.
4. Фронтенд и мобильная команда работают с заглушкой, не дожидаясь бэкенда.
5. Бэкенд реализует API строго по контракту.
6. Автоматические проверки сверяют, что реальный API соответствует спецификации.

Формат спецификации

Для REST API распространён стандарт OpenAPI: описание в формате YAML или JSON, где перечислены адреса, методы, параметры, схемы запросов и ответов, коды ошибок, способы авторизации. Из такого файла инструменты генерируют интерактивную документацию, заглушки, клиентские библиотеки и тесты. Для событийных интерфейсов существуют аналогичные форматы описания сообщений.

Что даёт заказчику

• Параллельная работа команд, а значит, меньше простоев
• Меньше переделок на стыке: договорённости зафиксированы до кода
• Документация API появляется сразу и не отстаёт от реальности
• Партнёры и подрядчики могут начать интеграцию раньше
• Проще сменить исполнителя одной из частей: контракт остаётся

Что должно быть в хорошей спецификации

• Единые правила именования полей и адресов
• Примеры запросов и ответов для каждого метода
• Описание всех ошибок, а не только успешного ответа
• Правила постраничной выдачи, сортировки и фильтров
• Форматы дат, денег, телефонов
• Авторизация и права для каждого метода
• Версия API и правила внесения изменений

Изменения контракта

Контракт не замораживается навсегда, но меняется по правилам. Добавление нового необязательного поля обычно безопасно. Удаление или переименование поля, изменение типа — ломающие изменения: они требуют новой версии API или периода, когда поддерживаются оба варианта. Любое изменение сначала вносится в спецификацию, а потом в код.

Ошибки при внедрении

• Спецификацию пишут после кода, «для документации», и она расходится с реальностью
• Контракт обсуждают только бэкенд-разработчики, без мобильной и веб-команды
• Нет автоматической проверки соответствия, и расхождения копятся
• Спецификация описывает внутреннюю структуру базы, а не потребности интерфейсов
• Изменения вносятся устно, в мессенджере, мимо документа

Когда подход особенно полезен

Несколько клиентов одного API: сайт, приложения под iOS и Android, Telegram-бот, мини-приложение. Несколько команд или подрядчиков. Публичный или партнёрский API. Системы, которые будут долго развиваться. Для небольшого проекта, где фронтенд и бэкенд пишет один человек, достаточно облегчённой версии — краткого описания API перед началом работы.

Итог

Сначала договориться о контракте, потом писать код — простая идея, которая убирает значительную часть конфликтов между командами и делает API предсказуемым для всех его потребителей.