api-designlisted

# API Design — REST + GraphQL Contracts A practical guide to designing APIs that consumers can build against without surprises. Stack-agnostic; concrete patterns target this project's stack (Go+Fiber for the business backend, Python+FastAPI for the AI adapter, React Native client). ## When to Use This Skill - Adding the first endpoint to a service — the contract you ship now will outlive three implementations. - Reviewing an OpenAPI / GraphQL schema PR before merge. - Adding a v2 version of a live endpoint without breaking v1 clients. - Debating REST vs GraphQL for a new bounded context. - Designing pagination, idempotency, rate-limit responses, batch endpoints. - Mapping domain errors (from a use case in your hexagonal architecture) to HTTP responses. Skip when: writing internal-only RPCs that have one caller and you control both sides — use whatever's fastest. ## The Contract Is the Product Three rules that override everything else: 1. **Consumers cannot read your code.** They read the contract. If the contract is ambiguous, the consumer guesses wrong, and you find out in production. 2. **Breaking changes are expensive forever.** Every consumer must coordinate. Plan as if you can't break things — because at scale, you can't. 3. **The use case shape is sacred. The API shape is negotiable.** Don't bend domain operations to match HTTP idioms. Translate at the adapter boundary (per hexagonal-architecture). ## REST vs GraphQL — Decision Pick **REST** when: - Consumers a