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-toneskill - Field Description Patterns - Load
ring:api-field-descriptionsskill - Documentation Structure - Load
ring:documentation-structureskill
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.