api-designer

# API Designer ## Overview This skill helps you design HTTP/REST and GraphQL APIs that are predictable, evolvable, and pleasant to consume. It covers resource modeling, URI design, HTTP semantics, versioning, pagination, filtering/sorting, error contracts, idempotency, concurrency control, auth, rate limiting, and writing machine-readable contracts. Keywords: REST, GraphQL, OpenAPI, Swagger, API design, endpoint, resource, versioning, pagination, cursor, idempotency, ETag, RFC 9457, Problem Details, rate limit, contract, HATEOAS, webhook. Apply this skill whenever the user is creating, extending, or reviewing an API surface — not when they are merely calling an existing third-party API. ## Decision: REST vs GraphQL vs RPC Pick the style before designing details. - **REST** — default for resource-oriented CRUD, public APIs, heavy caching needs, file uploads/downloads, and broad client tooling. Plays well with HTTP caching, CDNs, and standard status codes. - **GraphQL** — choose when clients need flexible, nested data selection, when you have many client types with divergent data needs, or to avoid over/under-fetching. Costs: caching, rate limiting, and observability are harder; needs query-depth/complexity limits. - **gRPC / JSON-RPC** — choose for internal service-to-service, low-latency, streaming, or strongly-typed contracts where browser reach is not required. When unsure, default to REST and expose a small GraphQL layer later if client flexibility becomes a real pai...