/meta-planning-api-planning

name: meta-planning-api-planning
description: Backend specification frameworks — endpoint contracts, error catalogs, auth per endpoint, schema with constraints and indexes, migration strategy, middleware order. Load when a spec adds or changes an API endpoint, a database table, or a request pipeline.

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](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](examples/core.md#api-contract-section).
• **It adds or changes a table, column or index** — one Database Schema block per table (Patterns 4–5), from the [Database Schema template](examples/core.md#database-schema-section).
• **It adds middleware or reorders a pipeline** — a Middleware Requirements section (Pattern 6), from the [Middleware Requirements template](examples/core.md#middleware-requirements-section).
• **None of the three** — nothing in this skill applies, and none of its sections belongs in the spec.

---

<critical_requirements>

Before writing a backend specification

**Read the closest existing route, schema file and middleware chain, and cite each by file and line range.** Their naming, pagination, response envelope and auth wiring are the vocabulary the spec reuses; a shape invented beside them diverges, and every consumer inherits the inconsistency.

**Give every endpoint its whole contract — method and path, auth, rate limit, request, success response and error catalog.** A part the spec leaves out is decided by the implementer, and decided again, differently, by each consumer.

**Name the consumers of every contract the spec changes, and what breaks for each.** Frontends, other services and external clients code against these shapes and status codes, and a change that names none ships without knowing who it breaks.

**Write schema as typed columns with their constraints, indexes with the query each serves, and a migration strategy.** A nullable, unique or foreign-key decision the spec omits is made by whoever writes the migration, and reversing it later is a second migration against production data.

</critical_requirements>

---

**Auto-detection:** `<api_contract>`, `<database_schema>`, `<middleware_requirements>`, API spec, endpoint contract, request and response shape, error catalog, status code per condition, auth per endpoint, rate limit, schema spec, soft delete, unique index, migration strategy, backfill, expand and contract, middleware order

**Applies to:**

• A new or changed endpoint's request, response, status codes, auth and rate limit
• Tables, columns, relationships and indexes, and the migration that delivers them
• The order of a request pipeline, and where validation and transactions sit in it

**Handled elsewhere:**

• Implementation — handler bodies, query code and migration files follow from the spec, which states contracts rather than code
• The interface that consumes the API — its states, forms and client state are specified separately; this skill names it as a consumer and stops there
• Model calls behind an endpoint — prompts, model choice and evaluation are specified separately; this skill covers the endpoint that exposes them
• The specification around these sections — goal, scope fence, out-of-scope list and success criteria belong to the planning process that loads this skill

---

<philosophy>

An API contract is a promise to consumers you cannot see. An ambiguous one does not stay ambiguous: the implementer resolves it one way and each consumer another, and the mismatch surfaces later as a bug in someone else's code.

So a backend spec is as much about what it leaves out:

• **The smallest set of endpoints that meets the goal** — each extra one is surface to secure, test and keep compatible
• **No columns for data no requirement names** — a speculative column still needs a constraint decision and a migration

</philosophy>

---

<patterns>

Core patterns

Pattern 1: Endpoint contract

Every endpoint the spec adds or changes carries all six parts.

- [ ] Method and exact path, with path parameters named (`GET /api/v1/users/:userId`)
- [ ] Auth: middleware and permission, or explicitly public (Pattern 2)
- [ ] Rate limit, or explicitly none
- [ ] Request: each parameter's location (path/query/body), type, required flag, constraints
- [ ] Success response: status code and body shape with field types
- [ ] Error catalog: a row per condition (Pattern 3)

BAD:  "Create an endpoint for user management"
GOOD: "GET /api/v1/users — cursor pagination as in routes/jobs.ts:45-67, at most 50
       per page. Response shape matches JobListResponse."

A list endpoint's constraints include its maximum page size; without one, a client can ask for the whole table in a single request.

Where the codebase generates a machine-readable API description from its routes — an OpenAPI document, say — the changed endpoint appears in it, and the spec's success criteria include that the description still