API Planning Frameworks

Quick Guide: Specify every endpoint as a complete contract — method, path, auth requirement, request shape, success response, and an error catalog with a status per condition. Specify schema as exact columns with constraints, relationships, indexes, and a migration strategy. Order the middleware pipeline explicitly. Apply a framework only when the spec touches its artifact class — an endpoint-only change needs no schema section.

<critical_requirements>

CRITICAL: Before Specifying Backend Contracts

All specifications must be grounded in the codebase's real routes, schemas, and middleware — reference specific files with line numbers

(You MUST give every endpoint a complete contract: method, path, auth requirement, request shape, success response shape, and an error catalog)

(You MUST state the auth requirement per endpoint — which middleware, which permission — never "endpoints should be protected")

(You MUST specify schema as exact columns with types, constraints, relationships, indexes, and a migration strategy)

(You MUST catalog error responses per endpoint — a status code per condition with its response body shape)