api-architectlisted

# api-architect — design the contract before writing the handler ## When to use this skill Trigger when the user needs an API design before implementation. Strong signals: - "design an API for <feature>" - "what should the endpoints look like?" - "REST or GraphQL for this use case?" - "give me an OpenAPI spec for X" - A feature spec or PRD pasted with no endpoint plan Do *not* trigger for: small additions to an existing API (just add the endpoint, matching local conventions), pure data modeling (use `schema-architect`), or when wrapping an existing API (use `mcp-forge`). ## The output contract A design artifact that includes: 1. **A short rationale** — 1 page. Why REST vs GraphQL, what trade-offs were made, what was deliberately left out. 2. **The schema** — OpenAPI 3.1 YAML for REST, or a GraphQL SDL with typed resolvers planned. 3. **Resource model** — what the nouns are, what the verbs are, what the relationships are. 4. **The boring-but-critical parts** — auth, pagination, filtering, errors, versioning. All explicit, all consistent. 5. **A "what's NOT in v1" section** — so reviewers don't argue about features that were intentionally deferred. ## Workflow ### 1 — Read the requirement, find the resources From the spec, list: - **Nouns**: the things users will create, read, update, delete (`Order`, `Customer`, `Invitation`) - **Verbs**: the actions that don't fit CRUD (`/orders/{id}/cancel`, `/invitations/{token}/accept`) - **Queries**: how users will find lists (`