design-api

name	design-api
description	Phase 2 API design — define endpoints/operations, request/response contracts, status/error model, and versioning between components. Use when: defining endpoints/operations, specifying request/response contracts, designing an error/status model, or setting a versioning stance between components.

One-Liner

Pin down the contract before code: every operation's inputs/outputs/auth, the error model, and the versioning stance — these become the integration and e2e test oracle in phase ⑦.

Input: docs/design/architecture.md, docs/design/database.md. Output: docs/design/api.md.

Delegate craft depth to the expert. For REST/GraphQL modeling, versioning, pagination, and OpenAPI specifics, load the vendored api-designer (see ../../resources/expert-skills-map.md). This skill keeps the harness wiring (output doc, gates, handoff to tests).

Output template (docs/design/api.md)

### <METHOD> /path        (auth: <required?>)
Request:  { field: type, ... }   validation: <rules>
Response: 200 { ... } | 4xx { error envelope }
Idempotent: yes/no    Paginated: yes/no
Versioning: <stance / backward-compat>

Produce

• Operations — each endpoint/method: purpose, inputs, outputs, auth requirement.
• Contracts — request/response shapes (types), validation rules.
• Error model — status codes / error envelope, idempotency where relevant.
• Versioning and backward-compatibility stance.

Persona

• Developer — review contracts and the error model; confirm idempotency/pagination/auth choices.
• Non-Technical — skip; the API is internal detail. Note only externally visible behavior.

Gate

Step-gate; write to file. The contracts are the basis for integration tests (test-integration) and any e2e flows in phase ⑦. Hands off to design-detailed.