playbooks

home / skills / lerianstudio / ring / writing-api-docs

writing-api-docs skill

/tw-team/skills/writing-api-docs

This skill guides you in writing API reference docs for endpoints, requests, responses, and errors with clear, consistent structure.

npx playbooks add skill lerianstudio/ring --skill writing-api-docs

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
4.8 KB
---
name: ring:writing-api-docs
description: |
  Patterns and structure for writing API reference documentation including
  endpoint descriptions, request/response schemas, and error documentation.

trigger: |
  - Documenting REST API endpoints
  - Writing request/response examples
  - Documenting error codes
  - Creating API field descriptions

skip_when: |
  - Writing conceptual guides → use writing-functional-docs
  - Reviewing documentation → use documentation-review
  - Writing code → use dev-team agents

sequence:
  before: [documentation-review]

related:
  similar: [writing-functional-docs]
  complementary: [api-field-descriptions, documentation-structure]
---

# 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., "[email protected]")` |
| 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:**
```json
{
  "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

Overview

This skill captures patterns and structure for writing clear, consistent API reference documentation covering endpoint descriptions, request/response schemas, and error documentation. It provides concrete conventions for titles, parameter tables, realistic examples, status codes, pagination, versioning and a quality checklist to enforce engineering best practices.

How this skill works

The skill defines a repeatable endpoint template: title, short description, HTTP method + path, path/query parameter tables, request body and response examples, and an errors table. It prescribes data type conventions (uuid, timestamptz, jsonb, enum), a standard error JSON shape, pagination fields, and explicit versioning/deprecation notes.

When to use it

  • Creating or updating API reference pages for REST endpoints
  • Onboarding new API authors to a consistent documentation standard
  • Auditing docs to ensure all parameters, responses, and errors are covered
  • Preparing API changelogs and deprecation notices between versions
  • Integrating docs into CI quality gates before release

Best practices

  • Use the endpoint template for every route: method+path, params, request, response, errors
  • Include realistic examples with actual UUIDs and timestamps, and show all returned fields
  • Mark deprecated fields and endpoints with clear migration guidance and version notes
  • Adopt a standard error format and list all possible error codes with resolutions
  • Document pagination parameters and response metadata for list endpoints

Example use cases

  • Documenting POST /v1/organizations/{orgId}/ledgers/{ledgerId}/accounts with request schema and 201 response
  • Creating an errors table for account retrieval endpoints, mapping status codes to resolutions
  • Replacing informal examples with realistic JSON responses for SDK consumers
  • Adding versioning note for an endpoint scheduled for removal in v4
  • Running a docs checklist in CI to confirm required vs optional fields are explicit

FAQ

What error format should I use?

Use a consistent JSON object with code, message, and optional details (e.g., {"code":"ACCOUNT_NOT_FOUND","message":"...","details":{}}).

How should I document enums and constraints?

List allowed values and constraints inline (e.g., currency, crypto) and show examples; note max length and format where relevant.