Patterns and structure for writing API reference documentation including endpoint descriptions, request/response schemas, and error documentation.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
name: writing-api-docs description: | Patterns and structure for writing API reference documentation including endpoint descriptions, request/response schemas, and error documentation.
trigger: |
skip_when: |
sequence: before: [ring-tw-team:documentation-review]
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."
| 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 |
| 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` |
| 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 |
Rules:
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 |
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)
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
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.