API documentation

API & Integration Documentation

Document endpoints, webhooks and integrations so a developer can call or receive them on the first try, handle every expected failure, and understand the side effects on data and background work.

1. Authentication, permissions and headers

• State how every request is authenticated (Bearer token, session cookie, HMAC signature, API key), where the credential comes from, and which routes are public or use a different mechanism.
• Document required headers (Content-Type, Authorization, Idempotency-Key, Last-Event-ID, custom headers) and any origin, host or size limits enforced by the server.
• State the authorization rule: which role, scope or resource ownership is required, and whether unauthorized access returns 401, 403 or 404.

2. Endpoint contract (method, path, input, output)

For each endpoint, derive the contract directly from the router, validator/schema and serializer:

• Method and path: exact route template (POST /api/projects/:projectId/work-items) and what each path parameter identifies.
• Query and body parameters: field name, type, required vs. optional, default value, validation constraints (min/max length, enum values, format) and meaning.
• Success response: HTTP status code (200, 201, 204) and a realistic example body that matches the serializer's actual output.
• Error responses: status codes (400, 401, 403, 404, 409, 422, 429, 500), the error envelope shape (code, message, details), and the specific conditions that trigger each code.

3. Side effects, idempotency and streaming

• Side effects: state what the call changes—database records created or transitioned, events emitted, background jobs queued, files written or external calls triggered.
• Idempotency and retries: explain whether repeating the request is safe, whether Idempotency-Key is supported, and what happens on duplicate submission or version conflict (409).
• Streams (SSE / WebSockets): document connection setup, event names, payload format, heartbeats, reconnection (Last-Event-ID) and which events are scoped to a project vs. global.

4. Webhooks and external integrations

• Inbound webhooks: document the URL, signature header and HMAC verification algorithm, expected event types, replay/duplicate protection, and what status code the sender expects within what timeout.
• Outbound integrations: document required configuration keys, timeouts, retry/backoff behavior, circuit-breaking or fallback behavior when the external service is down, and how to test locally without hitting live accounts.

Before you finish

• Auth method, required headers, permissions and body size limits documented.
• Path, query and body fields match the route's actual validation schema and defaults.
• Success and error status codes and JSON shapes match the handler and serializer.
• Side effects, idempotency, retries and streaming/webhook behavior are explicit.
• Example curl or client calls use safe placeholders and consistent identifiers.