writing-api-docs

Patterns and structure for writing API reference documentation includingendpoint descriptions, request/response schemas, and error documentation.

⭐25stars🔀1forks📁View on GitHub🕐Updated Dec 31, 2025⬇️4downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive framework and standardized patterns for creating high-quality API reference documentation. It helps developers and technical writers structure endpoint descriptions, define request/response schemas, and document error codes, ensuring consistency and clarity for API consumers through industry best practices.

Use Cases

  • Documenting new RESTful API endpoints with standardized tables for path parameters, query strings, and headers.
  • Creating precise request and response body schemas using consistent data types and realistic JSON examples.
  • Building robust error documentation that maps HTTP status codes to specific error messages and actionable resolution steps.
  • Implementing standardized field description patterns, including data constraints, examples, and deprecation notices.
  • Structuring complex API features like pagination, versioning, and authentication requirements for better developer experience.
namering:writing-api-docs
description|
trigger|
skip_when|
before[documentation-review]
similar[writing-functional-docs]
complementary[api-field-descriptions, documentation-structure]

Writing API Reference Documentation

API reference documentation describes what each endpoint does, its parameters, request/response formats, and error conditions. It focuses on the "what" rather than the "why."

API Reference Principles

  • RESTful and Predictable: Standard HTTP methods, consistent URL patterns, document idempotency
  • Consistent Formats: JSON requests/responses, clear typing, standard error format
  • Explicit Versioning: Version in URL path, backward compatibility notes, deprecated fields marked

Endpoint Documentation Structure

Section Content
Title Endpoint name
Description Brief description of what the endpoint does
HTTP Method + Path POST /v1/organizations/{orgId}/ledgers/{ledgerId}/accounts
Path Parameters Table: Parameter, Type, Required, Description
Query Parameters Table: Parameter, Type, Default, Description
Request Body JSON example + fields table
Success Response Status code + JSON example + fields table
Errors Table: Status Code, Error Code, Description

Field Description Patterns

Type Pattern
Basic name: string — The name of the Account
With constraints code: string — The asset code (max 10 chars, uppercase)
With example email: string — Email address (e.g., "user@example.com")
Deprecated chartOfAccountsGroupName: string — **[Deprecated]** Use \route` instead`

Data Types Reference

Type Description Example
uuid UUID v4 identifier 3172933b-50d2-4b17-96aa-9b378d6a6eac
string Text value "Customer Account"
integer Whole number 42
boolean True/false true
timestamptz ISO 8601 (UTC) 2024-01-15T10:30:00Z
jsonb JSON object {"key": "value"}
array List of values ["item1", "item2"]
enum Predefined values currency, crypto

Request/Response Examples

Rules:

  • Show realistic, working examples (not "foo", "bar")
  • Show all fields that would be returned
  • Use actual UUIDs, timestamps, realistic data

Error Documentation

Standard error format:

{
  "code": "ACCOUNT_NOT_FOUND",
  "message": "The specified account does not exist",
  "details": { "accountId": "invalid-uuid" }
}

Error table:

Status Code Description Resolution
400 INVALID_REQUEST Validation failed Check request format
401 UNAUTHORIZED Missing/invalid auth Provide valid API key
403 FORBIDDEN Insufficient permissions Contact admin
404 NOT_FOUND Resource doesn't exist Verify resource ID
409 CONFLICT Resource already exists Use different identifier
422 UNPROCESSABLE_ENTITY Business rule violation Check constraints
429 TOO_MANY_REQUESTS Rate limit exceeded Retry after delay
500 INTERNAL_ERROR Server error Retry or contact support

HTTP Status Codes

Success: 200 (GET/PUT/PATCH), 201 (POST creates), 204 (DELETE)

Client errors: 400 (malformed), 401 (no auth), 403 (no permission), 404 (not found), 409 (conflict), 422 (invalid semantics), 429 (rate limit)

Server errors: 500 (internal)


Pagination Documentation

For paginated endpoints, document query parameters:

Parameter Type Default Description
limit integer 10 Results per page (max 100)
page integer 1 Page number

Response includes: items, page, limit, totalItems, totalPages


Versioning Notes

Note: You're viewing documentation for the current version (v3).

For deprecated: > **Deprecated:** This endpoint will be removed in v4. Use [/v3/accounts](link) instead.


Quality Checklist

  • HTTP method and path correct
  • All path parameters documented
  • All query parameters documented
  • All request body fields documented with types
  • All response fields documented with types
  • Required vs optional clear
  • Realistic request/response examples included
  • All error codes documented
  • Deprecated fields marked
  • Links to related endpoints included