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 | | 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)

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

Standards Loading (MANDATORY)

Before writing any API documentation, MUST load relevant standards:

Voice and Tone Guidelines - Load ring:voice-and-tone skill
Field Description Patterns - Load ring:api-field-descriptions skill
Documentation Structure - Load ring:documentation-structure skill

HARD GATE: CANNOT proceed with API documentation without loading these standards.

Blocker Criteria - STOP and Report

| Condition | Decision | Action | |-----------|----------|--------| | API endpoint not implemented | STOP | Report: "Cannot document non-existent endpoint" | | API behavior undetermined | STOP | Report: "Need confirmed API behavior before documenting" | | Response schema unknown | STOP | Report: "Need response schema to document fields" | | Error codes undefined | STOP | Report: "Need error code list before completing" | | Voice/tone guidelines unclear | STOP | Report: "Need style guide clarification" |

Cannot Be Overridden

These requirements are NON-NEGOTIABLE:

MUST document ALL fields (request and response)
MUST include realistic examples (not "foo", "bar")
MUST document ALL error codes
MUST use present tense and active voice
MUST use sentence case for headings
CANNOT skip required vs optional indicators

Severity Calibration

| Severity | Criteria | Examples | |----------|----------|----------| | CRITICAL | Missing core sections, incorrect API paths | No request/response examples, wrong HTTP method | | HIGH | Missing field documentation, no error codes | Undocumented required fields, missing error table | | MEDIUM | Voice/tone violations, structure issues | Passive voice, title case headings | | LOW | Minor clarity improvements, formatting | Could add more context, spacing issues |

Pressure Resistance

| User Says | Your Response | |-----------|---------------| | "Skip the examples, developers will figure it out" | "CANNOT skip examples. Realistic examples are REQUIRED for every endpoint. I'll add complete request/response examples." | | "Just document the happy path, errors are rare" | "MUST document all error codes. Error handling is critical for developers. I'll include the complete error table." | | "The code is the documentation" | "Code is NOT documentation. API reference MUST explain purpose, constraints, and behavior. I'll write proper field descriptions." | | "We'll add docs later, ship the feature first" | "Documentation is part of the feature. CANNOT ship undocumented APIs. I'll complete the documentation now." | | "Copy the schema, that's enough" | "Schema alone is insufficient. MUST add descriptions, examples, and context. I'll write complete documentation." |

Anti-Rationalization Table

| Rationalization | Why It's WRONG | Required Action | |-----------------|----------------|-----------------| | "Field name is self-explanatory" | Self-explanatory to you ≠ self-explanatory to users | MUST write explicit description | | "Simple API doesn't need extensive docs" | Simplicity doesn't reduce documentation need | Document ALL fields completely | | "Error codes are standard HTTP" | Each error needs context and resolution guidance | MUST document all errors with resolutions | | "Examples slow down documentation" | Examples are the most-read part of API docs | MUST include realistic examples | | "Internal API, limited audience" | Internal users deserve quality docs too | Apply same standards as public APIs | | "Schema is generated, no need to write" | Generated schemas lack context and guidance | MUST add human-written descriptions |

When This Skill is Not Needed

Signs that API documentation already meets standards:

ALL endpoints have HTTP method, path, and description
ALL request fields documented with type, required status, constraints
ALL response fields documented with type and description
ALL error codes listed with descriptions and resolutions
Realistic JSON examples for every request and response
Links to related endpoints included
Voice and tone guidelines followed consistently

If all above are true: Documentation is complete, no changes needed.