api-design
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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add proyecto26/system-design-skills --skill api-design技能说明
name: api-design description: 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".
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 — drives pagination and whether reads
need their own optimized path (→
back-of-the-envelope). - Retry safety — can a write be safely repeated? Which operations are naturally idempotent (PUT/DELETE) vs not (POST that creates/charges)?
- Client diversity & churn — public third parties (slow to upgrade, need strict versioning) vs your own apps (ship together)?
- Latency & payload budget — mobile/high-latency links favor compact binary and fewer round trips; browsers favor cacheable HTTP.
The options
Protocol / style (pick per call shape)
- REST over HTTP/JSON — resource CRUD over standard verbs. Use as the default for public, cacheable, browser-friendly APIs.
- RPC / gRPC (HTTP/2, protobuf) — typed method calls, compact binary, streaming. Use for internal service-to-service traffic where latency and schema contracts matter.
- GraphQL — client specifies exactly the fields it wants in one query. Use when many clients need different shapes of the same graph and over/under-fetching on REST hurts.
- WebSocket / SSE (streaming) — persistent server→client push. Use when the server must push updates (chat, presence, live feeds) — see the polling tier below.
- Webhooks — server calls the client's URL on an event. Use for async, third-party event delivery.
Server-push tier (when clients need fresh data)
- Polling → long-polling → SSE → WebSocket, in increasing efficiency for push and increasing connection cost. Start at polling; escalate only when a number (update frequency, fanout) forces it.
Pagination
- Cursor (keyset) — opaque token over a stable sort key. Default for large or changing datasets.
- Offset/limit —
?offset=40&limit=20. Use only for small, mostly-static, jump-to-page lists.
Idempotency — client sends an Idempotency-Key on unsafe writes; the server
dedupes retries. This skill owns the key contract (see Interface sketch).
Versioning — URI (/v2/...), header (Accept: application/vnd.x.v2+json), or
additive/never-break. Prefer additive; reserve a new version for breaking changes.
Trade-offs
| Option | What it solves | What it worsens | Change it when |
|---|---|---|---|
| REST/JSON | Universal, cacheable, simple, tooling everywhere | Over/under-fetch; chatty for graphs; weak typing | Field-shaping pain → GraphQL; internal latency → gRPC |
| gRPC/RPC | Compact, typed, fast, native streaming | Not browser-native; needs proxy; opaque to HTTP caches | Public/browser clients need it → REST gateway |
| GraphQL | One round trip, client picks fields | Caching/rate-limiting hard; expensive queries (N+1); server complexity | Few fixed shapes (REST simpler) or query cost unbounded |
| WebSocket/SSE | True server push, low-latency updates | Stateful connections, harder to scale/LB, reconnection logic | Updates are infrequent → long-poll; one-way only → SSE |
| Cursor pagination | Stable under inserts; O(1) per page at any depth | Opaque token; no random page jump; needs sort key | Users must jump to page N of a static set → offset |
| Offset pagination | Trivial; arbitrary page jumps | Drift/dupes on insert; deep offsets scan & slow | Set grows or mutates → cursor |
| Idempotency keys | Safe retries; no double-charge | Server must store keys + dedupe; key TTL/scope to define | Op is naturally idempotent (PUT/DELETE) → may skip |
| URI versioning | Explicit, cache/log-visible, easy to route | Version sprawl; clients pinned forever | Changes are additive → no new version needed |
Behavior under stress
The contract decides how badly a client amplifies an incident.
- Retry storms. A timed-out write that isn't idempotent gets retried and may
double-execute; clients retrying in lockstep stampede a recovering service.
Idempotency keys make retries safe; the backoff/jitter that paces them is owned
by
resilience-failure. S