opencode-workflow/skills/api-contract-design/SKILL.md

name	description
api-contract-design	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:

{
  "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