Как согласовать и задокументировать контракт API между backend- и frontend/мобильной командами до того, как обе стороны начнут параллельную разработку?

Короткий ответ

Контракт стоит описать заранее в виде формальной спецификации (например, OpenAPI) с согласованными форматами запроса, ответа и ошибок, чтобы обе команды могли разрабатываться параллельно, ориентируясь на один и тот же документ, а не на устные договорённости.

Как это работает подробнее

Зафиксированный контракт позволяет frontend-команде начать разработку против заглушки (mock-сервера), сгенерированной из спецификации, не дожидаясь готовности backend, и наоборот — backend может валидировать реализацию против того же контракта. Это снижает риск интеграционных сюрпризов в конце спринта, когда на исправление расхождений остаётся мало времени.

Пример кода

contract.yamlКопировать

# Фрагмент согласованной OpenAPI-спецификации (contract-first подход)
paths:
  /api/v1/orders/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                required: [id, total_cents, currency, created_at]
                properties:
                  id: { type: integer }
                  total_cents: { type: integer, description: "сумма в копейках" }
                  currency: { type: string, example: "RUB" }
                  created_at: { type: string, format: date-time }

Что использовать на практике

• Практика. Стоит явно согласовать не только структуру успешного ответа, но и формат ошибок, пагинацию, обязательность полей и единицы измерения (например, цена в рублях или в копейках) — это частые источники расхождений. Изменения контракта в процессе разработки нужно вносить в общий документ и сообщать обеим сторонам, а не менять код молча. Полезно также зафиксировать, какая сторона считается источником истины при расхождении документации и фактической реализации.

Подводные камни

• Риски. Частая ошибка — начинать параллельную разработку по устной договорённости «примерно понятно, что там будет», из-за чего в конце обнаруживаются расхождения (например, фронтенд ждёт дату в формате ISO, а бэкенд отдаёт unix-timestamp). Другая ошибка — зафиксировать контракт один раз и не обновлять его при необходимости внести изменения, из-за чего документация расходится с реальным кодом. Также вредно согласовывать только структуру успешного ответа, забывая про форматы ошибок и edge-кейсы.