API FRD: функциональные требования для API-продуктов

API FRD описывает поведение системы, основной интерфейс которой — API: REST, GraphQL, gRPC или на основе вебхуков. Вместо экранных сценариев и UI-взаимодействий он определяет эндпоинты, схемы запросов и ответов, методы аутентификации, коды ошибок и лимиты запросов.

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

Key insight

API FRD — спецификация, на которую полагаются потребители API. Если FRD говорит, что ответ 404 содержит поле error_code, каждый API-клиент будет писать код под этот контракт. Изменить его позже — значит сломать интеграции.

Когда использовать API FRD

Используйте API FRD, когда:

• Вы строите публичный или партнёрский API, с которым будут интегрироваться внешние разработчики
• Система — микросервис, взаимодействующий с другими внутренними сервисами через API
• Нескольким командам нужен общий контракт, чтобы строить параллельно
• API выступает бэкендом для мобильного приложения, SPA или интеграции с третьей стороной

Стандартный FRD подойдёт лучше, когда:

• У системы значительный пользовательский интерфейс помимо API
• Бизнес-правила и рабочие процессы важнее спецификаций эндпоинтов
• Аудитория документа — бизнес-аналитики, а не бэкенд-инженеры

Секции API FRD

1. Обзор API

Краткое описание того, что API делает, кто его потребляет и как он вписывается в общую систему. Включает:

• Название и версию API
• Базовый URL (production, staging)
• Метод аутентификации (API key, OAuth 2.0, JWT)
• Транспортный протокол (HTTPS, gRPC)
• Формат данных (JSON, Protocol Buffers)

2. Аутентификация и авторизация

Точное описание того, как клиенты аутентифицируются и какую модель авторизации использует API.

Включите описание того, что происходит при неудачной аутентификации: формат тела ответа HTTP 401, коды ошибок и наличие заголовка Retry-After.

3. Эндпоинты

Ядро API FRD. Каждый эндпоинт получает отдельную подсекцию:

Формат спецификации эндпоинта:

Пример: эндпоинт создания заказа

POST /api/v1/orders

Request body:
{
  "customer_id": "string (required, UUID)",
  "items": [
    {
      "product_id": "string (required, UUID)",
      "quantity": "integer (required, min: 1, max: 999)"
    }
  ],
  "currency": "string (required, ISO 4217, e.g. 'USD')",
  "shipping_address_id": "string (optional, UUID)"
}

Response 201:
{
  "order_id": "string (UUID)",
  "status": "string (enum: created, processing, completed, cancelled)",
  "total_amount": "number (decimal, 2 places)",
  "created_at": "string (ISO 8601)"
}

Response 422:
{
  "error_code": "VALIDATION_ERROR",
  "message": "string",
  "details": [
    {
      "field": "string",
      "reason": "string"
    }
  ]
}

4. Обработка ошибок

Единый формат ответа об ошибке, который используют все эндпоинты:

Каждый ответ об ошибке должен содержать как минимум: error_code (машиночитаемый), message (для человека) и, при необходимости, details (ошибки на уровне полей для ответов 422).

5. Лимиты запросов и квоты

6. Версионирование

Как API обрабатывает критические изменения:

• URL-версионирование: /api/v1/, /api/v2/
• Политика устаревания: v(N-1) поддерживается 12 месяцев после выпуска v(N)
• Заголовок Sunset: Sunset: Sat, 01 Mar 2027 00:00:00 GMT

7. Модели данных

Общие модели данных, используемые в нескольких эндпоинтах. Это позволяет избежать повторения одной и той же схемы в каждой спецификации эндпоинта.

Order:
  order_id: string (UUID, read-only)
  customer_id: string (UUID)
  status: string (enum: created, processing, completed, cancelled)
  items: array of OrderItem
  total_amount: number (decimal, 2 places)
  currency: string (ISO 4217)
  created_at: string (ISO 8601, read-only)
  updated_at: string (ISO 8601, read-only)

OrderItem:
  product_id: string (UUID)
  quantity: integer (min: 1)
  unit_price: number (decimal, 2 places, read-only)
  subtotal: number (decimal, 2 places, read-only)

Типичные ошибки в API FRD

1. Нет спецификации ошибок. Определить happy path (200 OK) и не описать ответы об ошибках (4xx, 5xx) — значит оставить потребителей API гадать, как обрабатывать сбои.

2. Несогласованные форматы ответов. Одни эндпоинты возвращают { "error": "..." }, другие — { "message": "..." }. Единый формат ошибок по всем эндпоинтам избавляет потребителей API от написания специальных обработчиков для каждого эндпоинта.

3. Отсутствие ограничений полей. «quantity: integer» — недостаточно. «quantity: integer (required, min: 1, max: 999)» — точно указывает разработчику, что валидировать.

4. Нет стратегии версионирования. API без плана версионирования ломает клиентов при изменении схемы. Определите подход к версионированию до выпуска первого эндпоинта.

Ресурсы

• FRD — полное руководство — полный FRD со всеми семью секциями
• Шаблоны FRD — стандартный и API, готовы к использованию
• Промпт-генератор FRD — создайте FRD с помощью ИИ
• PRD vs BRD vs FRD — тройное сравнение