跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

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

OptionWhat it solvesWhat it worsensChange it when
REST/JSONUniversal, cacheable, simple, tooling everywhereOver/under-fetch; chatty for graphs; weak typingField-shaping pain → GraphQL; internal latency → gRPC
gRPC/RPCCompact, typed, fast, native streamingNot browser-native; needs proxy; opaque to HTTP cachesPublic/browser clients need it → REST gateway
GraphQLOne round trip, client picks fieldsCaching/rate-limiting hard; expensive queries (N+1); server complexityFew fixed shapes (REST simpler) or query cost unbounded
WebSocket/SSETrue server push, low-latency updatesStateful connections, harder to scale/LB, reconnection logicUpdates are infrequent → long-poll; one-way only → SSE
Cursor paginationStable under inserts; O(1) per page at any depthOpaque token; no random page jump; needs sort keyUsers must jump to page N of a static set → offset
Offset paginationTrivial; arbitrary page jumpsDrift/dupes on insert; deep offsets scan & slowSet grows or mutates → cursor
Idempotency keysSafe retries; no double-chargeServer must store keys + dedupe; key TTL/scope to defineOp is naturally idempotent (PUT/DELETE) → may skip
URI versioningExplicit, cache/log-visible, easy to routeVersion sprawl; clients pinned foreverChanges 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
阅读完整来源 ↗