API Documentation Format

Use this format for every module and submodule API page. The generated page must be accurate to the current codebase and must not invent endpoints, DTO fields, guards, permissions, response shapes, errors, or examples.

Required Source References

Before writing an API doc, inspect and cite the exact source files used.

Cross-Document Contract

Every generated API doc must link to the sibling docs for the same module:

Add a See Also section at the bottom with all three links.

Frontmatter

---
title: MODULE_NAME API Reference
description: Complete API contracts for MODULE_NAME, including routes, auth, DTOs, responses, errors, examples, and integration notes.
---

Page Header

# MODULE_NAME - API Reference

**Audience:** Frontend engineers, mobile engineers, backend engineers, QA, and API consumers.
**Scope:** Admin, public, mobile, internal, webhook, worker-triggered, and integration-facing APIs owned by MODULE_NAME.

1. Documentation Evidence

List every file inspected. The doc is not complete if this table is missing.

2. Module Summary

Document the module in plain terms.

3. Concepts and Terminology

Every domain term used by routes must be defined.

Include:

• Entity names and public identifiers.
• Status and lifecycle terms.
• Actor terms.
• Cache, job, event, or realtime names when exposed through API behavior.
• Any user-visible scoring, timing, ranking, or eligibility terminology.

4. API Surface Map

List every endpoint owned by the module or submodule.

Rules:

• Do not omit aliases, nested routes, restore endpoints, action endpoints, or list endpoints.
• Include route prefixes from module composition, not only controller decorators.
• If a route exists in Swagger but is composed through a parent module, document both the runtime path and the controller-local path.

5. Auth, Identity, and Permissions

Document exactly how identity reaches the service.

Explain:

• Which endpoints are public.
• Which endpoints support guests.
• Which endpoints require login.
• Which endpoints require admin permissions.
• Whether auth is optional or mandatory.
• Whether headers are parsed but not trusted.

6. DTO and Model Reference

Repeat this section for every request, query, response, and nested DTO.

6.x DTO_NAME

Include:

• Query DTOs.
• Body DTOs.
• Param DTOs if present.
• Response DTOs.
• Nested DTOs and arrays.
• Enum fields with every allowed value.
• Defaults from DTOs, services, schema, or DB.
• Server-generated fields and read-only fields.
• Fields accepted by DTO but ignored or overwritten by service.

7. Enum Reference

Every enum must be exhaustive.

8. Endpoint Reference

Repeat for every endpoint.

8.x METHOD /api/path

Purpose

Write 40-100 words explaining when the frontend, mobile app, admin panel, worker, or integration should call this endpoint.

Source Evidence

Auth and Permissions

• Auth:
• Guard chain:
• Permission:
• Guest support:
• Rate limit:
• Idempotency:

Request

{
  "field": "example"
}

Response

Document status code, envelope, data object, pagination, and all nullable fields.

{
  "success": true,
  "message": "Example",
  "data": {}
}

Side Effects

List all side effects:

• Database writes.
• Cache reads/writes/invalidation.
• BullMQ jobs.
• Realtime events.
• Analytics events.
• Email/push notifications.
• Audit logs.
• External API calls.

Error Cases

Edge Cases

Include all minor and major behavior:

• Empty input.
• Blank search.
• Invalid enum.
• Expired session.
• Duplicate request.
• Race condition.
• Cache miss.
• DB row missing.
• Guest trying a logged-in-only action.
• Unsupported filter or sort option.
• Rate-limit failure behavior.

Example Requests

POST /api/MODULE/path HTTP/1.1
Authorization: Bearer TOKEN
Content-Type: application/json

curl -X POST "$API_URL/api/MODULE/path" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field":"example"}'

9. Flow Diagrams

Include diagrams for every major route family and every important minor branch.

9.1 Route Ownership

9.2 Request Sequence

9.3 Error Branch

10. Pagination, Sorting, Filtering, and Search

Document every list endpoint.

Include:

• Shared pagination utility used.
• Broad-search detection.
• Relevance scoring.
• Cache behavior per query.
• Empty result behavior.

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

This section is required for every generated API doc. Do not summarize away small behavior. If a minor behavior exists in a controller, DTO, guard, interceptor, service, mapper, exception filter, cache layer, queue producer, or test, it must be documented.

13.1 Route-by-Route Completeness Matrix

Create one row for every concrete runtime route, including aliases and parent-module prefixes.

| Route | Controller Method | DTOs | Service Method | Guards | Permissions | Cache | Jobs | DB Touches | Errors | Tests | Documented? | |---|---|---|---|---|---|---|---|---|---|---|---|---| | METHOD /api/... | Controller.method | DtoName | Service.method | Guard list | Permission list | Key or N/A | Job or N/A | Event or N/A | Tables | Codes | Spec path | Yes/No |

Rules:

• Every @Get, @Post, @Patch, @Put, @Delete, and custom route decorator must appear.
• Every route-level, controller-level, and global guard that affects the route must appear.
• Every interceptor, pipe, decorator, and response-status override must appear if it changes behavior.
• Every service method called directly or indirectly by the route must be linked.

13.2 Request/Response Exhaustiveness

For every endpoint, include all examples below when applicable:

13.3 API Diagram Pack

Every API doc must include diagrams that match the API surface.

Example activity diagram:

Example request/response data contract map:

13.4 Consumer Integration Notes

Document exactly how frontend, mobile, admin, QA, and external consumers should use the API.

13.5 API Tradeoffs and Rationale

Every non-trivial API design choice needs a short rationale.

Include tradeoffs for:

• Route shape and nesting.
• Public vs authenticated access.
• Guest vs logged-in behavior.
• Pagination and result caps.
• Cacheability.
• Idempotency.
• Async vs synchronous side effects.
• Response DTO shape.
• Backward compatibility.

13.6 API Change Impact

Document what breaks if the API changes.

14. Zero-Omission API Checklist

Use this as the final gate before publishing.

• Every controller route is documented.
• Every parent route prefix and runtime URL is documented.
• Every DTO field, nested field, enum, default, transform, and validator is documented.
• Every response field, nullable field, generated field, and omitted raw entity field is documented.
• Every auth, guard, permission, role, public decorator, and guest identity branch is documented.
• Every success, validation, auth, permission, not-found, conflict, rate-limit, and server-error branch is documented.
• Every database read/write, cache hit/miss/write/invalidation, queue job, realtime event, notification, audit log, and external call is documented.
• Every route has examples for minimal request, full request, success response, and representative failures.
• Every endpoint family has route, sequence, activity, and error diagrams.
• Every tradeoff and compatibility risk is documented.
• The API doc links to backend, features/flows, and TDD.

15. Integration Checklist

• Every route from controllers is documented.
• Every DTO field is documented.
• Every enum value is documented.
• Every response envelope is documented.
• Every error code is documented.
• Every auth guard and permission is documented.
• Every cache key, queue job, realtime event, and external call is documented.
• Every diagram matches the current code.
• The API doc links to backend, features/flows, and TDD.

See Also

• Backend doc: /docs/developer/MODULE_SLUG/backend
• Features and flows doc: /docs/developer/MODULE_SLUG/feature
• TDD: /docs/developer/MODULE_SLUG/tdd