API Documentation Template

Template Structure

Use this template as the foundation for documenting any HTTP API. Replace bracketed sections with your API-specific content.

---

1. Overview

Base URL

https://api.example.com/v1

Authentication

All endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <your_api_key>

Content-Type

Requests and responses use application/json unless specified otherwise. See Parse JSON for handling JSON payloads.

Rate Limits

• 100 requests per minute for authenticated users
• 10 requests per minute for anonymous users
• Rate limit headers included in all responses:
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

---

2. Endpoints

[Resource Name]

GET /[resource]

List all [resources] with optional filtering and pagination.

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (default: 20, max: 100)
sort	string	No	Sort field and direction (created_at:desc)
filter[field]	string	No	Filter by field value

Response 200 OK

{
  "data": [
    {
      "id": "string",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "total_pages": 5
  }
}

POST /[resource]

Create a new [resource].

Request Body

{
  "name": "string (required, max 255 chars)",
  "description": "string (optional, max 1000 chars)"
}

Response 201 Created

{
  "id": "string",
  "name": "string",
  "description": "string",
  "created_at": "2026-01-01T00:00:00Z"
}

GET /[resource]/{id}

Retrieve a single [resource] by ID.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique resource identifier

Response 200 OK

{
  "id": "string",
  "name": "string",
  "description": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

PATCH /[resource]/{id}

Partially update a [resource]. Only provided fields are modified.

Request Body

{
  "name": "string (optional)",
  "description": "string (optional)"
}

Response 200 OK

{
  "id": "string",
  "name": "string",
  "description": "string",
  "updated_at": "2026-01-01T00:00:00Z"
}

DELETE /[resource]/{id}

Delete a [resource] by ID.

Response 204 No Content

---

3. Error Responses

All errors follow this structure. For a dedicated error response template, see API Error Response Template. See Input Validation for request validation patterns.

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable description",
    "details": [
      {
        "field": "name",
        "issue": "is required"
      }
    ]
  }
}

Common HTTP Status Codes

Status	Code	Description
400	bad_request	Malformed request or validation error
401	unauthorized	Missing or invalid authentication
403	forbidden	Insufficient permissions
404	not_found	Resource does not exist
409	conflict	Resource conflict (e.g., duplicate unique field)
422	unprocessable_entity	Semantic validation error
429	rate_limited	Too many requests
500	internal_error	Server-side error

---

4. SDKs & Tools

• cURL: All examples use standard cURL commands
• Postman: Import our [OpenAPI spec](https://api. example. com/openapi.
• OpenAPI: Auto-generated spec available at `/openapi.

---

5. Changelog

Version	Date	Changes
1.0.0	2026-06-10	Initial release

---

Customization Guide

1. Replace [resource] with your actual domain entity (e.g., users, orders, products)
2. Add endpoint-specific query parameters and response fields
3. Include authentication examples for OAuth, API keys, or JWT
4. Add code examples in Python, JavaScript, and Java
5. Link to your OpenAPI/Swagger spec for interactive documentation

Troubleshooting

• 5xx errors under load: check rate limits, connection pools, and downstream timeouts.
• CORS errors in the browser: confirm allowed origins, methods, and headers. Preflight requests must return the right headers before the actual request.
• Unexpected 404s: verify route definitions, path parameters, and base paths. Watch for trailing slashes and URL encoding differences.
• Authentication failures: validate token expiry, signature algorithms, and clock skew. Log rejected tokens without exposing secrets.
• Slow response times: profile the slowest percentiles.

Key Takeaways

• Apply api documentation template when you need a practical solution for your use case.
• Monitor performance after implementation; measure latency, errors, and resource usage before and after.
• Check the Troubleshooting section for common failures; most have documented root causes with fixes.
• Keep dependencies updated and run tests in CI to prevent production regressions.

Variant Comparison

Variant	Context	Approach	Notes
REST with OpenAPI	Public API, external clients	OpenAPI spec + narrative docs	Generates clients automatically
GraphQL with schema	API with flexible queries	Schema SDL + query examples	Single endpoint
gRPC with proto	Internal microservices	.proto files + generated docs	Binary, high performance
Simple Markdown	Small internal API	Manual docs in repo	Sufficient for 2-3 endpoints

Detailed Scenario: Documenting an Order Creation Endpoint

Endpoint: POST /v1/orders
Authentication: Bearer token (JWT)
Rate limit: 100 req/min per user

Request:
  POST /v1/orders HTTP/1.1
  Host: api.example.com
  Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
  Content-Type: application/json
  Idempotency-Key: client-uuid-12345

  {
    "customer_id": "usr_abc123",
    "items": [
      {"sku": "PROD-001", "quantity": 2},
      {"sku": "PROD-002", "quantity": 1}
    ],
    "shipping_address_id": "addr_xyz789"
  }

Response 201 Created:
  HTTP/1.1 201 Created
  Content-Type: application/json
  Location: /v1/orders/ord_def456

  {
    "id": "ord_def456",
    "customer_id": "usr_abc123",
    "status": "pending",
    "items": [
      {"sku": "PROD-001", "quantity": 2, "unit_price_cents": 1999},
      {"sku": "PROD-002", "quantity": 1, "unit_price_cents": 4999}
    ],
    "total_cents": 8997,
    "currency": "USD",
    "placed_at": "2026-07-11T14:30:00Z"
  }

Key headers:
  Idempotency-Key: Prevents duplicates on client retry
  Location: URL of created resource for redirect

Possible errors:
  400 - customer_id does not exist or is inactive
  409 - Idempotency-Key already used with different body
  422 - quantity <= 0 or SKU not found

How do I document cursor-based vs offset-based pagination?

Document both if you support them. Offset-based uses page and limit (simpler, but slow on large datasets). Cursor-based uses after (an ID or opaque cursor) and limit (more efficient, no skipped records). Include examples of both in the documentation and recommend cursor-based for datasets exceeding 10,000 records.

Should I include code examples in multiple languages?

If your API has consumers in multiple languages, yes. Include examples in cURL (universal), Python (requests), and JavaScript (fetch). Keep examples short and focused on one endpoint each. For internal APIs with a single consuming language, one language is enough.

Common Production Pitfalls

• Leaving required fields blank or using vague one-word answers.
• Filling the document once and never updating it after scope or decisions change.
• Storing the document where the team does not look during incidents or reviews.
• Not assigning an owner, due date, or review cadence.
• Copying boilerplate without removing sections that do not apply.
• Skipping version control, which makes rollback and accountability impossible.
• Failing to link the document to related decisions or follow-up actions.
• Avoiding quarterly reviews that would retire stale or unused sections.