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
1---2name: ring-writing-api-docs3description: Patterns and structure for writing API reference documentation including endpoint descriptions, request/response schemas, and error documentation.4---5
6# Writing API Reference Documentation
7
8API reference documentation describes what each endpoint does, its parameters, request/response formats, and error conditions. It focuses on the "what" rather than the "why."
9
10## API Reference Principles
11
12- **RESTful and Predictable:** Standard HTTP methods, consistent URL patterns, document idempotency
13- **Consistent Formats:** JSON requests/responses, clear typing, standard error format
14- **Explicit Versioning:** Version in URL path, backward compatibility notes, deprecated fields marked
15
16---
17
18## Endpoint Documentation Structure
19
20| Section | Content |
21|---------|---------|
22| **Title** | Endpoint name |
23| **Description** | Brief description of what the endpoint does |
24| **HTTP Method + Path** | `POST /v1/organizations/{orgId}/ledgers/{ledgerId}/accounts` |
25| **Path Parameters** | Table: Parameter, Type, Required, Description |
26| **Query Parameters** | Table: Parameter, Type, Default, Description |
27| **Request Body** | JSON example + fields table |
28| **Success Response** | Status code + JSON example + fields table |
29| **Errors** | Table: Status Code, Error Code, Description |
30
31---
32
33## Field Description Patterns
34
35| Type | Pattern |
36|------|---------|
37| Basic | `name: string — The name of the Account` |
38| With constraints | `code: string — The asset code (max 10 chars, uppercase)` |
39| With example | `email: string — Email address (e.g., "user@example.com")` |
40| Deprecated | `chartOfAccountsGroupName: string — **[Deprecated]** Use \`route\` instead` |
41
42---
43
44## Data Types Reference
45
46| Type | Description | Example |
47|------|-------------|---------|
48| `uuid` | UUID v4 identifier | `3172933b-50d2-4b17-96aa-9b378d6a6eac` |
49| `string` | Text value | `"Customer Account"` |
50| `integer` | Whole number | `42` |
51| `boolean` | True/false | `true` |
52| `timestamptz` | ISO 8601 (UTC) | `2024-01-15T10:30:00Z` |
53| `jsonb` | JSON object | `{"key": "value"}` |
54| `array` | List of values | `["item1", "item2"]` |
55| `enum` | Predefined values | `currency`, `crypto` |
56
57---
58
59## Request/Response Examples
60
61**Rules:**
62- Show realistic, working examples (not "foo", "bar")
63- Show all fields that would be returned
64- Use actual UUIDs, timestamps, realistic data
65
66---
67
68## Error Documentation
69
70**Standard error format:**
71```json
72{
73 "code": "ACCOUNT_NOT_FOUND",
74 "message": "The specified account does not exist",
75 "details": { "accountId": "invalid-uuid" }
76}
77```
78
79**Error table:**
80
81| Status | Code | Description | Resolution |
82|--------|------|-------------|------------|
83| 400 | INVALID_REQUEST | Validation failed | Check request format |
84| 401 | UNAUTHORIZED | Missing/invalid auth | Provide valid API key |
85| 403 | FORBIDDEN | Insufficient permissions | Contact admin |
86| 404 | NOT_FOUND | Resource doesn't exist | Verify resource ID |
87| 409 | CONFLICT | Resource already exists | Use different identifier |
88| 422 | UNPROCESSABLE_ENTITY | Business rule violation | Check constraints |
89| 429 | TOO_MANY_REQUESTS | Rate limit exceeded | Retry after delay |
90| 500 | INTERNAL_ERROR | Server error | Retry or contact support |
91
92---
93
94## HTTP Status Codes
95
96**Success:** 200 (GET/PUT/PATCH), 201 (POST creates), 204 (DELETE)
97
98**Client errors:** 400 (malformed), 401 (no auth), 403 (no permission), 404 (not found), 409 (conflict), 422 (invalid semantics), 429 (rate limit)
99
100**Server errors:** 500 (internal)
101
102---
103
104## Pagination Documentation
105
106For paginated endpoints, document query parameters:
107
108| Parameter | Type | Default | Description |
109|-----------|------|---------|-------------|
110| limit | integer | 10 | Results per page (max 100) |
111| page | integer | 1 | Page number |
112
113Response includes: `items`, `page`, `limit`, `totalItems`, `totalPages`
114
115---
116
117## Versioning Notes
118
119> **Note:** You're viewing documentation for the **current version** (v3).
120
121For deprecated: `> **Deprecated:** This endpoint will be removed in v4. Use [/v3/accounts](link) instead.`
122
123---
124
125## Quality Checklist
126
127- [ ] HTTP method and path correct
128- [ ] All path parameters documented
129- [ ] All query parameters documented
130- [ ] All request body fields documented with types
131- [ ] All response fields documented with types
132- [ ] Required vs optional clear
133- [ ] Realistic request/response examples included
134- [ ] All error codes documented
135- [ ] Deprecated fields marked
136- [ ] Links to related endpoints included
majiayu000