Как обычно проектируют и согласовывают API-контракт между фронтендом и бэкендом?

Question

Обычно начинают с описания требований и сценариев, затем фиксируют контракт в виде спецификации (часто OpenAPI) или схем (JSON Schema). Договариваются о форматах запросов/ответов, кодах ошибок и правилах обратной совместимости. Часто применяют подход contract-first: сначала спецификация, потом реализация. Для снижения конфликтов подключают мок-серверы и контрактные тесты. Изменения проводят через версионирование или эволюцию схем с сохранением совместимости.

YeaHub · Accepted Answer

Процесс проектирования API-контракта — это сочетание технических договорённостей и регламента изменений, чтобы фронтенд не «падал» от неожиданных правок.ОпределениеОпределение: API-контракт — это договорённость о том, какие запросы можно отправлять (методы, параметры, заголовки) и какие ответы придут (структура JSON, статусы, ошибки, ограничения), включая правила изменения этих договорённостей.Типичный процесс согласованияСбор сценариевКакие страницы/фичи должны работатьКакие данные нужны фронту (минимально достаточный набор)Проектирование форматаРесурсы и эндпоинты (/users, /orders/{id})Поля, типы, обязательность, значения по умолчаниюФиксация спецификацииOpenAPI/Swagger или JSON SchemaПримеры запросов/ответов, включая ошибкиПараллельная разработкаФронт использует mock или stub (мок-сервер)Бэк реализует согласно спецификацииПроверка совместимостиКонтрактные тесты, CI-проверкиРевью изменений контракта как отдельный артефактЧто важно проговорить в контрактеОшибкиЕдиный формат ошибки (код, сообщение, детали)Как отличать валидацию от системной ошибкиПагинация, сортировка, фильтрыПараметры (limit, cursor, sort)Нейминг и стабильностьsnake_case vs camelCaseМожно ли добавлять поля без предупреждения (обычно да)Backwards compatibilityДобавление новых полей — безопасноУдаление/переименование — через версию или длительную фазу deprecatedПрактика: пример контракта ошибки{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Некорректные данные",
    "details": { "email": "invalid format" }
  }
}
Версионирование и измененияЭволюция без версии (предпочтительно)Добавлять поля, не ломая старые клиентыНовое поведение — за флагом/параметромВерсионирование (когда ломаете контракт)/v2/... или Accept: application/vnd.app.v2+jsonЧёткая политика поддержки версий (например, 6–12 месяцев)ВыводКонтракт лучше фиксировать формально (OpenAPI/Schema), договориться о правилах изменений и использовать моки + контрактные тесты — это уменьшает «сломали фронт» и ускоряет параллельную разработку.