--- name: meta-planning-api-planning description: Backend specification planning frameworks. Use when a spec touches API endpoints, database schema, middleware, or auth. Covers endpoint contracts with request/response shapes, error catalogs, auth per endpoint, schema design with constraints and indexes, migration strategy, and middleware pipeline ordering. --- # 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: 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)** **(You MUST apply each framework only when the spec touches its artifact class — an unused section is omitted, never filled)** --- **Auto-detection:** API spec, endpoint design, REST contract, request response shape, database schema spec, migration plan, middleware ordering, auth requirements, error catalog **When to use:** - Specifying new or changed API endpoints (request/response contracts) - Specifying database tables, columns, relationships, or indexes - Specifying auth and permission requirements per endpoint - Specifying middleware pipelines and their ordering - Specifying error response catalogs - Planning migrations (reversibility, data migration, downtime) **When NOT to use:** - When implementing backend code (use the relevant API implementation skill) - For the frontend that consumes the API (use the web planning skill) - For model-calling capabilities behind an endpoint (use the ai planning skill) - For the planning PROCESS itself — research, scope fencing, success criteria — which the PM agent carries **Key patterns covered:** - Endpoint contract completeness (method, path, auth, shapes, errors) - Auth specification per endpoint - Error response catalogs - Database schema design (columns, constraints, relationships, indexes) - Migration strategy - Middleware pipeline ordering - Consumer-contract awareness (who breaks on change) **Detailed Resources:** - [examples/core.md](examples/core.md) - Per-artifact spec section templates and a worked example specification --- ## Philosophy **An API contract is a promise to consumers you cannot see.** Frontends, other services, and external clients all code against the shapes and status codes the spec defines. An ambiguous contract does not stay ambiguous — it gets resolved differently by the implementer and each consumer. **When specifying backend work:** - Read the closest existing route first; its naming, middleware chain, and response envelope are the vocabulary the spec must reuse - Name the downstream consumers of every contract, and what breaks for each if the shape changes - Specify the error catalog with the same care as the success path — consumers branch on status codes - Treat the schema as a contract too: a column without constraints is a decision deferred to whoever writes the migration **When NOT to specify:** - Don't add endpoints beyond the smallest set that achieves the goal - Don't design schema columns for data no requirement names - Don't invent new middleware when an existing chain covers the requirement - Don't specify implementation (handler bodies, ORM calls) — contracts and schemas, not code **Core principles:** - **Auth is per endpoint**: "protected" is not a specification; the middleware and permission are - **Errors are a catalog**: every condition a consumer can hit has a status code and a body shape - **Schema constraints are requirements**: nullable, unique, and FK decisions belong in the spec - **Migrations are planned, not improvised**: reversibility, data migration, and downtime are stated up front --- ## Core Patterns ### Pattern 1: Endpoint Contract Completeness Every endpoint the spec introduces or changes carries all six parts. ```markdown ## Endpoint Contract For EACH endpoint: - [ ] Method and exact path, with path parameters named (`GET /api/v1/users/:userId`) - [ ] Auth requirement: middleware name + permission/role, or explicitly public - [ ] Rate limit, or explicitly none - [ ] Request shape: every parameter with location (path/query/body), type, required flag, constraints - [ ] Success response: status code and exact body shape with field types - [ ] Error catalog: a row per condition (see Pattern 3) ``` ``` BAD: "Create an endpoint for user management" GOOD: "GET /api/v1/users — paginated list with cursor-based pagination following routes/jobs.ts:45-67. Response shape matches JobListResponse." ``` **Why this matters:** each missing part becomes an invention. An invented pagination style or response envelope diverges from the codebase's own, and consumers inherit the inconsistency permanently. --- ### Pattern 2: Auth Per Endpoint State the requirement per endpoint, naming real middleware. ``` BAD: "Endpoints should be protected" GOOD: "GET /api/v1/users requires authMiddleware. DELETE /api/v1/users/:id requires authMiddleware + adminGuard. Public: POST /api/v1/auth/login." ``` **Rules the spec must state:** - Which middleware, from which file, applied to which route group or individual route - The permission model: role, ownership (`ownerGuard` — user edits own resource only), or tenancy - Which fields are private (returned only to the owner or an admin) versus public - What an unauthorized versus a forbidden request returns — 401 and 403 are different promises --- ### Pattern 3: Error Response Catalog Every endpoint's failure surface, as a table consumers can branch on. | Status | Condition | Response Body | | ------ | ----------------------------------------- | ----------------------------------- | | 400 | Validation failure (schema parse error) | `{ error: string, details: [...] }` | | 401 | Missing or expired token | `{ error: string }` | | 403 | Authenticated but insufficient permission | `{ error: string }` | | 404 | Resource not found | `{ error: string }` | | 409 | Unique constraint violation | `{ error: string }` | | 422 | Business rule violation | `{ error: string }` | **Rules the spec must state:** - Reuse the codebase's error envelope — one error shape per API, not per endpoint - One status per condition class a consumer handles differently; two conditions handled identically share a status - Validation failures name the offending fields in `details`, in the shape the existing error handler emits - Whether 404 is returned for a resource that exists but is not visible to the caller (existence leakage is a decision) --- ### Pattern 4: Database Schema Design Specify tables as exact columns, never as prose. ```markdown ## Schema Review Checklist For EACH table the spec adds or changes: - [ ] Every column: name, type (with length/precision), constraints (NOT NULL, UNIQUE, FK, default) - [ ] Pattern source: the existing schema file whose conventions it follows - [ ] Audit columns per the codebase convention (createdAt, updatedAt) - [ ] Soft delete per the codebase convention (deletedAt), and the isNull check on every query - [ ] Relationships: cardinality and the FK or join table that carries each - [ ] Indexes: columns, type, and the query each index serves ``` ``` BAD: "Add a users table" GOOD: "Add users table following db/schema/jobs.ts:12-45. Soft delete (deletedAt), audit columns, composite unique index on (email, deletedAt)." ``` **Why this matters:** a column that arrives without constraints gets its NOT NULL, uniqueness, and FK decisions made by whoever types the migration — and changed later at the cost of a second migration against production data. --- ### Pattern 5: Migration Strategy Every schema change states three things before implementation starts: | Concern | State | | -------------- | ---------------------------------------------------------------------- | | Reversibility | Reversible (and how), or irreversible and why that is acceptable | | Data migration | None, or describe: source of the backfilled values, and the batch plan | | Downtime | None, or why it is required and the window | **Rules the spec must state:** - New NOT NULL columns on existing tables need a default or a backfill step — state which - Renames are two deploys (add + dual-write, then remove), or a breaking change named as such - Which environments the migration has been sized against, when tables are large --- ### Pattern 6: Middleware Pipeline Order is behavior. State the pipeline explicitly per route group. ```markdown ## Request Pipeline Order 1. Rate limiting — if applicable 2. Auth middleware — which one 3. Input validation — schema reference 4. Business logic handler 5. Response serialization ``` **Rules the spec must state:** - New middleware only when existing middleware cannot cover the requirement — name what was checked - Which existing middleware is reused, from which file - Where validation happens (before the handler, with which schema) so handlers never see unvalidated input - Transaction boundaries for multi-step operations — which steps commit together --- ## Decision Framework ### Which Spec Sections Does This Feature Need? Apply a framework only when the spec touches its artifact class. The per-artifact section templates live in [examples/core.md](examples/core.md). ``` Does the spec add or change an endpoint? ├─ YES → API Contract section (Patterns 1-3), one block per endpoint └─ Does it add or change tables, columns, or indexes? ├─ YES → Database Schema section (Patterns 4-5), one block per table └─ Does it add or reorder middleware? ├─ YES → Middleware Requirements section (Pattern 6) └─ NO → None of these frameworks applies; do not force one in ``` ### Common Spec Failures | Failure | Consequence | | ---------------------------------------- | ------------------------------------------------------------------- | | "User data" instead of an exact shape | The implementer and each consumer resolve the ambiguity differently | | "Protected" instead of named middleware | Auth drifts per endpoint; a route ships public that should not be | | No error catalog | Consumers cannot branch; every client wraps calls in generic catch | | Schema as prose | Constraint decisions deferred to the migration author | | No migration strategy | Irreversible change discovered during deploy | | Endpoint set larger than the requirement | Unused surface to secure, test, and maintain | | No named consumers | A shape change ships without knowing who breaks | --- ## RED FLAGS **High Priority Issues (a spec with one of these is incomplete):** - An endpoint without a request shape, response shape, or error catalog - Auth stated as "protected" without naming middleware and permission - A schema change without column constraints or a migration strategy - A new NOT NULL column on an existing table with no default and no backfill plan - Validation placement unstated — handlers seeing unvalidated input **Medium Priority Issues:** - A response envelope that differs from the codebase's existing one - An index without the query it serves - Soft-delete tables without the isNull convention stated for queries - Multi-step operations without a transaction boundary decision - 401 vs 403 conflated **Common Mistakes:** - Designing pagination differently from the sibling endpoints - Specifying a join table where the codebase uses an FK convention (or vice versa) - Leaving rate limits unstated on public endpoints - Forgetting the "not visible vs not found" existence-leakage decision **Gotchas & Edge Cases:** - A unique constraint on a soft-delete table usually needs the deletedAt column in the index - Renames are two deploys; a spec that renames in one is specifying a breaking change - An endpoint that returns different fields to owners and strangers is two response shapes — specify both --- ## CRITICAL REMINDERS > **All specifications must be grounded in the codebase's real routes, schemas, and middleware** **(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)** **(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)** **(You MUST apply each framework only when the spec touches its artifact class — an unused section is omitted, never filled)** **Failure to specify these contracts produces APIs whose implementers invent shapes, whose consumers break on drift, whose auth gaps ship silently, and whose migrations cannot be rolled back.**