---
name: api-contract-design
description: "Knowledge contract for defining API contracts, request/response schemas, status codes, pagination, authentication boundaries, and idempotency behavior. Referenced by design-architecture when defining APIs."
---

This is a knowledge contract, not a workflow skill. It is referenced by `design-architecture` when the architect is defining API contracts.

## Core Principles

- APIs are contracts between producers and consumers; stability and clarity are paramount
- Every endpoint must serve at least one PRD functional requirement
- Contracts must be explicit, complete, and unambiguous
- Breaking changes must be avoided; versioning must be planned

## REST API Design

### Endpoint Definition

For each endpoint, define:
- HTTP method (GET, POST, PUT, PATCH, DELETE)
- Path (e.g., `/api/v1/jobs`)
- Description
- PRD functional requirement it satisfies
- Authentication requirements
- Idempotency behavior (when applicable)

### Request Schema

For each endpoint, define:
- Path parameters (name, type, description, validation rules)
- Query parameters (name, type, required/optional, default, validation rules)
- Request headers (name, required/optional, purpose)
- Request body (JSON schema with types, required fields, validation rules)

### Response Schema

For each endpoint, define:
- Success response (status code, body schema)
- Error responses (each status code, body schema, conditions that trigger it)
- Pagination metadata (when applicable)

### Status Codes

Use status codes semantically:
- `200 OK` - successful retrieval or update
- `201 Created` - successful resource creation
- `204 No Content` - successful deletion or action with no response body
- `400 Bad Request` - client sent invalid input
- `401 Unauthorized` - missing or invalid authentication
- `403 Forbidden` - authenticated but not authorized
- `404 Not Found` - resource does not exist
- `409 Conflict` - state conflict (duplicate, version mismatch)
- `422 Unprocessable Entity` - valid format but business rule violation
- `429 Too Many Requests` - rate limit exceeded
- `500 Internal Server Error` - unexpected server error
- `502 Bad Gateway` - upstream service failure
- `503 Service Unavailable` - temporary unavailability
- `504 Gateway Timeout` - upstream timeout

### Pagination Model

For list endpoints, define:
- Pagination strategy (cursor-based recommended, offset-based acceptable)
- Page size limits (default and maximum)
- Sort order (default and available fields)
- Total count availability (when to include, performance implications)

Cursor-based pagination is preferred for:
- Large datasets
- Real-time data that shifts during pagination
- Performance-sensitive endpoints

Offset-based pagination is acceptable for:
- Small, stable datasets
- When random access by page number is required

### Filtering & Sorting

For list endpoints, define:
- Available filter parameters and their types
- Filter combination rules (AND, OR, support for complex queries)
- Sort fields and sort direction
- Default sort order

### Authentication Boundary

Define:
- Which endpoints require authentication
- Authentication mechanism (API key, JWT, OAuth, etc.)
- Token scope requirements per endpoint
- Rate limiting per authentication tier (when applicable)

### Error Response Format

Define a consistent error response schema:
```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": [
      {
        "field": "field_name",
        "code": "VALIDATION_ERROR",
        "message": "Specific error message"
      }
    ]
  }
}
```

### Versioning Strategy

- Prefer URL path versioning (e.g., `/api/v1/`) for public APIs
- Prefer header versioning for internal APIs when appropriate
- Define breaking vs non-breaking change policy
- Define deprecation timeline for old versions

## Non-REST APIs

### GraphQL
- Define schema (types, queries, mutations, subscriptions)
- Define resolver contracts
- Define pagination model (cursor-based connections)
- Define error handling in responses

### gRPC
- Define service definitions in proto files
- Define message types
- Define streaming patterns
- Define error status codes

### WebSocket
- Define message schema (message types, payload formats)
- Define connection lifecycle (connect, reconnect, disconnect)
- Define authentication for initial connection
- Define error handling within messages

## API Contract Anti-Patterns

- Endpoints without a PRD functional requirement
- Vague or inconsistent error response formats
- Missing pagination on list endpoints
- Authentication applied inconsistently
- Breaking changes without versioning
- Over-nested response structures
- Exposing internal implementation details through API shape