API FRD: functional requirements for API products

An API FRD specifies the behavior of a system whose primary interface is an API — REST, GraphQL, gRPC, or webhook-based. Instead of describing screen flows and UI interactions, it defines endpoints, request/response schemas, authentication methods, error codes, and rate limits.

The document serves the same purpose as a standard FRD: give developers and QA an exact specification of how the system should behave. The difference is scope — an API FRD focuses on the contract between systems rather than the contract between a system and a human user.

Key insight

An API FRD is the specification that API consumers rely on. If the FRD says a 404 response includes an error_code field, every API client will code against that contract. Changing it later breaks integrations.

When to use an API FRD

Use an API FRD when:

• You are building a public or partner-facing API that external developers will integrate with
• The system is a microservice that communicates with other internal services via API
• Multiple teams need a shared contract before they can build in parallel
• The API serves as the backend for a mobile app, SPA, or third-party integration

A standard FRD is better when:

• The system has a significant user-facing interface alongside the API
• Business rules and workflows are more important than endpoint specifications
• The audience is business analysts rather than backend engineers

Sections of an API FRD

1. API overview

A brief description of what the API does, who consumes it, and how it fits into the larger system. Include:

• API name and version
• Base URL (production, staging)
• Authentication method (API key, OAuth 2.0, JWT)
• Transport protocol (HTTPS, gRPC)
• Data format (JSON, Protocol Buffers)

2. Authentication and authorization

Specify exactly how clients authenticate and what authorization model the API uses.

Include what happens when authentication fails: HTTP 401 response body format, error codes, and whether the response includes a Retry-After header.

3. Endpoints

The core of the API FRD. Each endpoint gets its own subsection with:

Endpoint specification format:

Example: Create order endpoint

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 handling

Define a consistent error response format that all endpoints use:

Every error response should include at minimum: error_code (machine-readable), message (human-readable), and optionally details (field-level errors for 422 responses).

5. Rate limiting and quotas

6. Versioning

How the API handles breaking changes:

• URL versioning: /api/v1/, /api/v2/
• Deprecation policy: v(N-1) supported for 12 months after v(N) release
• Sunset header: Sunset: Sat, 01 Mar 2027 00:00:00 GMT

7. Data models

Define shared data models that appear across multiple endpoints. This avoids repeating the same schema in every endpoint specification.

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)

Common mistakes in API FRDs

1. No error specification. Defining the happy path (200 OK) but not the error responses (4xx, 5xx) leaves API consumers guessing how to handle failures.

2. Inconsistent response formats. Some endpoints return { "error": "..." }, others return { "message": "..." }. A single error format across all endpoints saves API consumers from writing special handling per endpoint.

3. Missing field constraints. “quantity: integer” is incomplete. “quantity: integer (required, min: 1, max: 999)” tells the developer exactly what to validate.

4. No versioning strategy. APIs without a versioning plan break clients when the schema changes. Define the versioning approach before the first endpoint ships.

Resources

• FRD — the complete guide — full FRD with all seven sections
• FRD templates — Standard and API, ready to use
• FRD generator prompt — create an FRD using AI
• PRD vs BRD vs FRD — triple comparison