mkapi-designlisted

# API Design REST and GraphQL design patterns for building consistent, developer-friendly APIs. ## When to Use Activate when: - Designing a new API or set of endpoints - Reviewing existing endpoint structure for consistency - User asks "design this API", "REST patterns", "how should I structure endpoints" - Backend architecture planning phase ## Phase Anchor **Phase: 1 (Plan)** — Produces an API design document before implementation begins. **Handoff:** Developer agent implements the endpoints per the design document. ## Process 1. **Identify API type** — REST, GraphQL, or both. Default to REST unless user specifies otherwise. 2. **Load patterns** — Load `references/rest-patterns.md` for REST; `references/graphql-patterns.md` for GraphQL. 3. **Map resources** — Identify domain entities and their relationships. 4. **Design endpoints** — Apply naming, HTTP semantics, and status code conventions. 5. **Define error format** — Establish consistent error response structure. 6. **Plan pagination** — Choose cursor-based (preferred) or offset-based with justification. 7. **Specify versioning strategy** — URL prefix or Accept header. 8. **Document rate limiting** — Headers and throttle thresholds. 9. **Output design document** — Endpoint table + request/response examples. ## References | File | Purpose | |------|---------| | `references/rest-patterns.md` | Resource naming, HTTP methods, status codes, pagination, versioning, rate limiting, error format | | `references/graphql-p