SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdev-api-design

dev-api-design

Coding & development

View repository

Updated 10-15 23:25

About this skill

API Design

Use this skill for contract-first API design across REST, GraphQL, gRPC, tRPC, AsyncAPI, and agent-facing interfaces. It owns contract choice, auth boundaries, versioning, errors, pagination, rate limits, idempotency, and validation; it does not replace backend implementation or security review.

Style Decision Table

API style Choose when Avoid when Canonical artifact
REST + OpenAPI Public APIs, broad tooling compatibility, cacheable resources Streaming-first service contracts OpenAPI 3.x
GraphQL Complex client-driven query shapes, multi-team schema ownership Simple CRUD, caching is critical, single-team GraphQL SDL
gRPC Internal services, bidirectional streaming, type-critical boundaries Public internet consumers, browser-native clients protobuf
tRPC TypeScript monorepos with shared server+client Non-TS stacks, public third-party consumers TypeScript types
AsyncAPI + webhooks Event-driven contracts, pub/sub, push notifications Synchronous request-reply AsyncAPI 3.x
MCP tool layer Agent or LLM is the primary consumer Human-only clients MCP tool schema

Quick Reference

API style Load
REST + OpenAPI references/restful-design-patterns.md, references/openapi-guide.md
GraphQL references/graphql-patterns.md
gRPC references/grpc-patterns.md
tRPC references/trpc-patterns.md
AsyncAPI and webhooks references/asyncapi-patterns.md, references/webhook-patterns.md
Core cross-cutting references/error-handling-patterns.md, references/authentication-patterns.md, references/pagination-filtering.md, references/rate-limiting-patterns.md, references/api-testing-patterns.md

Contract Review Checklist

Run on every API contract before handoff:

  • Canonical spec artifact exists (OpenAPI, AsyncAPI, protobuf, GraphQL SDL, or MCP schema)
  • Compatibility and versioning model named: evolutionary changes, URL path (/v1/), header, or content-type negotiation
  • Deprecation timeline written into the spec or linked doc; Deprecation header uses the RFC 9745 @<unix-seconds> form, Sunset uses RFC 8594
  • Error model: for REST/HTTP, use RFC 9457 Problem Details with stable type URI and an application code extension when clients need one; for GraphQL, gRPC, and events, define errors in their native contract
  • Auth boundary: which endpoints require which scopes; token type (JWT, opaque); revocation path
  • Pagination: cursor-based for high-cardinality; offset only for small, stable sets
  • Rate limits: either the IETF httpapi RateLimit / RateLimit-Policy fields or a documented legacy X-RateLimit-* triad; 429 includes Retry-After. The IETF fields have changed shape between drafts: look up the current revision and RFC status on the IETF datatracker and copy the syntax from that revision, and name the revision in the spec
  • Idempotency: POST/PATCH operations document idempotency key or mark non-idempotent explicitly; whatever the IETF Idempotency-Key header's status (check datatracker), the spec must define key scope, retention, and the reused-key response
  • Long-running jobs: 202 + Location poll URL; state enum with terminal states named
  • Webhooks: HMAC signature; replay protection; trace_id on payload
  • Breaking-change detection: oasdiff or equivalent configured in CI
  • Contract tests: Schemathesis (property-based) or Pact (consumer-driven) wired up

Workflow

  1. Choose the API style using the decision table above.
  2. Define the canonical contract artifact.
  3. Run the contract review checklist.
  4. Add contract validation, breaking-change detection, and documentation.
  5. Hand off spec, examples, and rollout notes.

Compatibility evidence by change class

Classify each change before calling the contract compatible:

Change class Required evidence
shape change schema diff plus generated-client compile or consumer contract test
semantic change with stable shape before/after examples and a named behavioral assertion
default, ordering, quota, or timeout change production-like consumer test and rollout note
removal or narrowing usage evidence, deprecation window, and rollback or compatibility shim

For provider/consumer deployments, derive the safe order from message direction, changed payload side, and actual consumer tolerance. For a new optional request capability, ship provider support before consumers send it. For response enum/event expansion, or whenever a consumer may reject unknown fields or variants, ship and verify tolerant consumers before the provider emits the new value. For removals, ship consumers first, confirm old-field traffic is gone, then remove the provider behavior. Prove the relevant consumer behavior rather than inferring safety from schema additivity; a green schema diff alone is insufficient evidence for semantic compatibility or deploy order.

Route Elsewhere

Defaults

  • Define the contract before implementation or code generation.
  • Use RFC 9457 Problem Details for REST/HTTP errors that need a response body; define native error shapes for other API styles.
  • Make versioning, deprecation, idempotency, pagination, and rate limits explicit in the spec.
  • Prefer OpenAPI 3.x or AsyncAPI as the canonical source for HTTP or event-driven interfaces; pin the newest minor that every validator, linter, and generator in your pipeline supports.
  • Treat agent APIs as domain contracts with clear side effects, not thin wrappers around random endpoints.
  • Use MCP as the tool-exposure layer when an agent is the primary consumer. Its authorization model builds on OAuth resource-server standards (RFC 9728 Protected Resource Metadata, RFC 8707 Resource Indicators), but session, handshake, and auth requirements change between spec revisions: look up the current revision at modelcontextprotocol.io before designing around sessions or the initialize handshake. See references/llm-agent-api-contracts.md.

Versioning Strategy Table

Approach When to use Breaking-change gate
URL path versioning (/v2/) Public APIs, broad client install base oasdiff --fail-on ERR in CI
Header versioning (API-Version: 2) Internal APIs, frequent iteration oasdiff on each PR
Content-type negotiation Hypermedia or media-type-driven APIs Manual review + tests
Evolutionary (GraphQL, gRPC) Teams own schema, introspection tools run GraphQL Inspector / protobuf compatibility

Expert Judgment

Versioning strategy — pick based on who controls the client, not team preference.

  • If you do not control every client (public API, third-party integrators, mobile apps you cannot force-update), publish a version policy and a support window based on observed consumer use and migration lead time; you cannot silently migrate callers.
  • If you control every client (internal service mesh, monorepo with generated clients), prefer evolutionary compatibility (additive fields, deprecate-then-remove) over versioning — a new version number is a coordination tax you don't need to pay.
  • Dated versions can be useful when each account or request pins behavior independently. If requests omit a version, resolve to a documented pinned default rather than silently upgrading callers, and echo the resolved version in a response header.
  • Never let "evolutionary" become an excuse to skip a compatibility gate — GraphQL and gRPC still need CI-enforced schema diffing (GraphQL Inspector, buf breaking); "no versioning" is not "no discipline."

Rule: rules/api/contracts.md loads this invariant when Claude edits a matching file.

Breaking-change detection instincts — what schema-diff tools structurally cannot catch:

The instances below are all applications of Hyrum's Law: with enough consumers of an API, every observable behavior — not just the documented schema — becomes a de facto contract, whether or not you ever promised it. (Same law, applied to schema deploy-sequencing rather than API surface, in software-database-design/references/migration-strategies.md.) That is why a clean schema diff is not proof of compatibility:

  • Semantic changes with no shape change: tightening an existing enum's allowed values, narrowing a previously-permissive validation rule, or changing what a field means while keeping its type — oasdiff/buf breaking will report zero diff.
  • Behavioral defaults: changing a default sort order, default page size, or default timeout is a breaking change for callers who rely on the default, even though the schema is untouched.
  • Cross-field coupling: a field that used to be optional-but-ignored becoming optional-but-enforced (e.g., a previously-cosmetic region field now affecting routing).
  • Rate-limit and quota tightening: not a contract break in the schema sense, but it breaks production traffic identically to a removed field — treat quota changes with the same deprecation-notice discipline as field removal.
  • Error-code reclassification: moving a case from 404 to 410, or from a generic code to a more specific one, breaks clients that pattern-match on the old code even though the Problem Details shape is unchanged.
  • Treat automated diffing (oasdiff, GraphQL Inspector, buf breaking, Pact) as a floor, not a ceiling — pair it with a changelog review by someone who understands what callers actually depend on.

Hyrum's Law framing adapted from addyosmani/agent-skills (MIT), commit 7676817, 2026-08-09.

When GraphQL, gRPC, or event-driven contracts are the wrong choice:

  • GraphQL is wrong for simple CRUD with one client shape, for teams that need HTTP-cache semantics (the GraphQL-over-HTTP spec requires POST support and makes GET optional, so many servers accept only POST; HTTP caching then needs GET plus persisted queries), and for single-team ownership where the query-flexibility payoff is never realized — you inherit N+1 risk, query-complexity DoS surface, and federation tooling cost for no client benefit.
  • Native gRPC is a poor default for browser clients, which need gRPC-Web or a compatible transport layer. For public third-party integrators, account for protobuf tooling and transport support; choose REST+OpenAPI when broad HTTP interoperability and discoverability matter more.
  • AsyncAPI/event contracts are wrong when the caller needs an immediate, correlated answer to a specific request — forcing request/response workflows through pub/sub adds correlation-ID bookkeeping and timeout ambiguity that plain synchronous HTTP avoids.
  • The tell that a style choice was fashion, not fit: nobody on the team can name the specific latency budget, client platform constraint, or multi-team ownership problem the chosen style solves.

Known Traps

  • Picking GraphQL, gRPC, or AsyncAPI for architectural fashion instead of actual client, latency, or interoperability constraints.
  • Designing happy-path resources without an explicit idempotency and retry story for duplicated or partial-failure requests.
  • Letting auth stay implicit until implementation, producing inconsistent enforcement across endpoints.
  • Reusing pagination models that leak internal storage semantics into the public contract.
  • Treating webhook or event delivery as reliable push without signature validation, replay protection, or consumer backpressure.
  • Generating a spec from code after implementation and calling it contract-first.
  • Wrapping arbitrary internal endpoints as agent APIs without stable side-effect, auth, and validation rules.

Navigation

Core patterns:

Style-specific:

Assets and templates:

Related skills:

Learnings Loop

When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.