API Documentation Template

Overview

Describe what this API does, who it is for, and when you would use it. A developer should be able to read this section and know whether this is the right API for their use case.

Connection & Access

How to connect to and authenticate with this API. Adapt the sections below to your API style — not every field applies to every protocol.

Endpoints / Connection Details

Authentication

Describe how consumers authenticate. Include the mechanism (API key, OAuth 2.0, mTLS, service account, JWT) and where credentials go (header, metadata, query param, certificate).

# Example: Bearer token (REST/GraphQL)
curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com/v1/resource

# Example: gRPC metadata
grpcurl -H "authorization: Bearer $TOKEN" grpc.example.com:443 service.Method

# Example: API key
curl -H "X-API-Key: $KEY" https://api.example.com/v1/resource

Authorization Model

Describe the permission model. What scopes, roles, or policies control access? How does a consumer request elevated permissions?

API Contract

This section documents the operations, types, and behaviors your API exposes. Structure it according to your API style.

Operations

Document each operation with its purpose, input, output, and an example. Use the table below as a summary index, then provide detailed documentation for each operation.

Operation Detail: [Operation Name]

Document one operation in full. Duplicate this subsection for each operation that needs detailed documentation.

Request example:

# Adapt to your API style
curl -X GET "https://api.example.com/v1/resources?limit=10&offset=0" \
  -H "Authorization: Bearer $TOKEN"

Response example:

{
  "data": [
    {
      "id": "res_abc123",
      "name": "Example Resource",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0
  }
}

Data Types / Schemas

Document the core data structures your API uses. For REST/GraphQL, these are your response shapes. For gRPC, these are your protobuf messages. For event-driven APIs, these are your event payloads.

Error Handling

Document how errors are communicated. Every API style has a different error mechanism — HTTP status codes, gRPC status codes, GraphQL errors array, SOAP faults — but the principle is the same: give the consumer enough information to understand what went wrong and how to fix it.

Error Response Format

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource does not exist.",
    "details": {
      "resource_id": "res_abc123"
    },
    "request_id": "req_xyz789"
  }
}

Error Codes

Pagination, Filtering & Sorting

If your API returns lists, document the pagination strategy. Different strategies have different trade-offs:

Document your specific implementation: what parameters control pagination, how the consumer gets the next page, and what the maximum page size is.

Rate Limiting & Quotas

Document the rate limits and how they are communicated to consumers. If limits differ by tier, plan, or operation, make that clear.

Rate limit feedback (adapt to your API style):

• REST: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers

• gRPC: Rate limit info in trailing metadata or RESOURCE_EXHAUSTED status with retry-after detail

• GraphQL: Rate limit info in the extensions field of the response

Reliability & Resilience

Document the operational characteristics that consumers need to build reliable integrations. This section is the difference between an API that works in a demo and one that works in production.

SLA / SLO

Retry & Idempotency

Guide consumers on how to safely retry failed requests:

• Which operations are idempotent and safe to retry without side effects?

• For non-idempotent operations: does the API support an idempotency key? How should the consumer pass it?

• Recommended retry strategy: exponential backoff with jitter, max retries, circuit breaker thresholds

Timeouts

Recommended client-side timeout settings:

Versioning & Deprecation

Document how the API evolves without breaking consumers. This is where trust is built or destroyed.

Events & Webhooks

If this API emits events (webhooks, message queue topics, server-sent events, WebSocket messages), document them here. If not applicable, delete this section.

• Delivery mechanism: HTTP webhook / message queue (Kafka, SQS, Pub/Sub) / WebSocket / SSE

• Retry policy: How many times, how long between retries, what happens after max retries?

• Ordering: Are events guaranteed to arrive in order? If not, how should consumers handle out-of-order delivery?

• Signature verification: How consumers verify that the event is authentic (HMAC, JWT, mTLS)

SDKs & Client Libraries

List the official and community-maintained client libraries. If none exist, document how to generate a client from the API definition (OpenAPI codegen, protoc, GraphQL codegen).

Observability & Debugging

Help consumers debug integration issues. This section saves your support team hundreds of hours.

• Request ID: Every response includes a request_id (or trace ID). Include this in support requests.

• Status page: Link to your API status page for incident and maintenance updates

• Health check endpoint: Link or describe the health/readiness probe consumers can poll

• Logging recommendations: What should consumers log on their side for effective debugging?

• Sandbox / test mode: How to test the integration without affecting production data

• Support channel: Where to get help (Slack channel, email, issue tracker, forum)

Changelog

Track changes to the API contract. Consumers rely on this to understand what changed and whether they need to update their integration.