api-designlisted

This skill should be used when the user needs to "design the API", do "endpoint design", pin down a "request/response shape", choose a "pagination" strategy (cursor vs offset), add an "idempotency key" to a write, plan "API versioning", an "error contract", or pick between "REST vs gRPC vs GraphQL" or "WebSocket vs polling". Use it whenever a design has reached the interface — the concrete request, response, primary access path, and how clients page, retry, and version — even if the user only said "the boxes talk to each other".
proyecto26/system-design-skills · ★ 6 · API & Backend · score 76

Install: claude install-skill proyecto26/system-design-skills

# API Design Define the contract between clients and a service: the exact request and response shapes, how callers page through data, how retried writes stay safe, how errors are reported, and how the contract evolves. Get this vague and the rest of the diagram is guesswork (GUIDE #8) — a "NoSQL box" or "user service" solves nothing until you can write the request, the response, and the key it hits. ## When to reach for this The design has named services and a datastore, and you now need the *interface*: what a client sends, what it gets back, how it fetches the next page, how it retries a payment without double-charging, and how a v1 client survives a v2 deploy. Reach here the moment someone says "fetch the feed" or "store the post" without a shape. ## When NOT to Before requirements and scale are pinned — the protocol choice depends on read/write ratio and latency target, not taste (→ `requirements-scoping`, `back-of-the-envelope`). Don't reach for gRPC, GraphQL, or streaming because they sound modern; a plain REST/JSON endpoint is the cheapest contract that meets most constraints, and naming a fancier protocol you don't need is a YAGNI red flag. Internal data-access keys and partition design live in `data-storage`; this skill designs the *external* contract that mirrors them. ## Clarify first - **Call shape** — request/response (CRUD), bidirectional/real-time, or one request → many results (streaming)? This picks the protocol. - **Read/write ratio and result-set size