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

Процесс проектирования API-контракта — это сочетание технических договорённостей и регламента изменений, чтобы фронтенд не «падал» от неожиданных правок.

Определение

Определение: API-контракт — это договорённость о том, какие запросы можно отправлять (методы, параметры, заголовки) и какие ответы придут (структура JSON, статусы, ошибки, ограничения), включая правила изменения этих договорённостей.

Типичный процесс согласования

1. Сбор сценариев

   • Какие страницы/фичи должны работать

   • Какие данные нужны фронту (минимально достаточный набор)

2. Проектирование формата

   • Ресурсы и эндпоинты (/users, /orders/{id})

   • Поля, типы, обязательность, значения по умолчанию

3. Фиксация спецификации

   • OpenAPI/Swagger или JSON Schema

   • Примеры запросов/ответов, включая ошибки

4. Параллельная разработка

   • Фронт использует mock или stub (мок-сервер)

   • Бэк реализует согласно спецификации

5. Проверка совместимости

   • Контрактные тесты, 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), договориться о правилах изменений и использовать моки + контрактные тесты — это уменьшает «сломали фронт» и ускоряет параллельную разработку.