API Planning Frameworks

Quick Guide: Specify each endpoint as a contract a consumer can code against without asking: method, path, auth, rate limit, request, success response, and a status for every failure. Specify each table as typed, constrained columns, indexes with the query each serves, and a migration strategy, and state the middleware order. Three facts change the answer more often than expected: a partial update is PATCH, not PUT; a unique index that includes a nullable deletedAt does not stop duplicate live rows in most SQL databases; and renaming a column without an outage takes three phases, not one migration.

Detailed Resources:

• examples/core.md — the API Contract, Database Schema and Middleware Requirements section templates, and a worked specification built from them

Which path applies

Ask each question on its own; a spec that adds an endpoint and a table carries both sections. A section with nothing to say is left out rather than filled.

• It adds or changes an endpoint — one API Contract block per endpoint (Patterns 1–3), from the API Contract template.
• It adds or changes a table, column or index — one Database Schema block per table (Patterns 4–5), from the Database Schema template.
• It adds middleware or reorders a pipeline — a Middleware Requirements section (Pattern 6), from the Middleware Requirements template.
• None of the three — nothing in this skill applies, and none of its sections belongs in the spec.