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

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.

ring:writing-api-docs