From bee-tw-team
Patterns and structure for writing API reference documentation including endpoint descriptions, request/response schemas, and error documentation.
npx claudepluginhub luanrodrigues/ia-frmwrk --plugin bee-tw-teamThis skill uses the workspace's default tool permissions.
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."
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
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 |
| 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)
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.
Before writing any API documentation, MUST load relevant standards:
bee:voice-and-tone skillbee:api-field-descriptions skillbee:documentation-structure skillHARD GATE: CANNOT proceed with API documentation without loading these standards.
| 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" |
These requirements are NON-NEGOTIABLE:
| 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 |
| 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." |
| 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 |
Signs that API documentation already meets standards:
If all above are true: Documentation is complete, no changes needed.