api-design-craft

name	api-design-craft
description	API quality, taste, and review craft — the layer above api-design methodology. Canonical APIs (Stripe, S3, Linear, GitHub, Twilio, Resend), Bloch core as review checklist, robust-API canon (RFC 9457, cursor pagination, idempotency, versioning), REST vs GraphQL vs gRPC selection, HTTP status code semantics (Retry-After, 422 vs 400), PATCH semantics, webhook design, long-running ops, low-latency ergonomics (N+1, ETag, DataLoader). Triggers: reviewing API quality, applying a taste lens, choosing a paradigm, designing error contracts/pagination/webhooks, evaluating latency ergonomics. Methodology in api-design; agentic tool design in agentic-interface-design.
allowed-tools	["Read","Glob","Grep","Bash"]
compatibility	Claude Code
staleness_sensitive_sections	["The Standards Canon","Rate Limiting","Connection Reuse"]

API Design Craft

This skill is the quality and taste lens for REST, GraphQL, and gRPC APIs. It answers: Is this API good? The api-design skill answers: How do I structure an API?

The difference matters for context loading: use api-design when building an API from scratch (methodology, OpenAPI spec patterns, resource modeling process). Use this skill when reviewing an API design, applying a quality lens, studying the canonical examples, or making a paradigm choice under trade-offs.

Start with the shared canon in references/design-fundamentals.md — Bloch's principles are the foundation of this skill's entire review framework.

Satellite files (loaded on-demand):

• references/design-fundamentals.md -- durable design canon (Rams, Norman, Nielsen, Bloch) — the first-principles foundation
• references/api-canon.md -- canonical APIs (Stripe, GitHub, S3, Twilio, Linear, Resend) and standards (RFC 9457, OpenAPI 3.1, Relay, Google AIP)
• references/rest-patterns.md -- REST quality patterns: URL design, status codes, PATCH semantics, webhooks, long-running ops, versioning
• references/graphql-patterns.md -- GraphQL quality patterns: when to use, schema design, Relay, error unions, DataLoader
• references/grpc-patterns.md -- gRPC quality patterns: Protobuf design, FieldMask, streaming modes, Google AIP
• references/low-latency-ergonomics.md -- N+1 elimination, caching (ETag, Cache-Control), streaming decisions, round-trip cost
• references/design-review-checklist.md -- audit checklist for REST/GraphQL/gRPC APIs

The Canon Summary

API	Domain	One Durable Lesson
Stripe	Payments	Treat the API as a product: design the error object first, design the list envelope first, use idempotency keys from day one
GitHub REST v3	Developer platform	REST is the right choice when reach and caching matter; GraphQL was introduced for their specific over-fetch problem, not because REST was bad
AWS S3	Object storage	Minimal surface area ages well. S3's ~20 years of stability is proof
Twilio	Telephony	A complex domain can be tamed by aggressive resource modeling behind business-concept nouns
Linear GraphQL	Project management	GraphQL errors belong in the type system: `union { Success
Resend	Email	Simplicity is a competitive advantage — you can out-compete incumbents on API quality alone

Deep treatment of each, plus the standards canon (OpenAPI 3.1, RFC 9457, RFC 9110, Relay, Richardson Maturity Model, Google AIP, Zalando): references/api-canon.md.

Bloch Core as Review Checklist

Apply Joshua Bloch's 8 principles as the primary review checklist for any API:

Principle	Review question
Minimal surface area	Is every element necessary? What can be removed without loss of capability?
Names matter	If you can't name it well, is the design wrong? Are names self-documenting?
Hard to misuse > easy to use	Is incorrect usage immediately obvious? Is correct usage the path of least resistance?
Fail fast	Are errors reported as early as possible (schema validation, not runtime)?
Principle of Least Astonishment	Does every endpoint do the least surprising thing given its name?
Consistency > local cleverness	Are naming, pagination, and error shapes consistent across all endpoints?
Document religiously	Does every element have a description? Does every error have a resolution path?
Avoid long parameter lists	Are there endpoints that accept many parameters of the same type?

Robust API Canon

Practice	Why it matters
Idempotency keys for mutations	Networks are unreliable; clients will retry; duplicate side effects are silent bugs
At-least-once delivery, idempotent receivers	For webhooks: reliability and duplicate protection are separate concerns
Pagination from day one	"Works fine in dev, OOMs in prod" is a recurring failure mode
RFC 9457 errors as first-class citizens	Callers handle errors programmatically; string parsing is not an interface
Cursor pagination at scale	Offset is O(n) in the DB; cursor is consistent under concurrent mutation
Versioning discipline	You cannot un-ship an API; additive-only within a version
Retries with backoff and jitter	Synchronized retries amplify failures; jitter breaks the thundering herd

Paradigm Selection: REST / GraphQL / gRPC

Dimension	REST	GraphQL	gRPC
Primary strength	Resources, caching, broad reach	Client-driven field selection	Internal service-to-service, streaming
Caching	Native HTTP (ETag, Cache-Control, CDNs)	Application-layer only	Not applicable (binary)
Tooling breadth	Highest (curl, Postman, everything)	High (Apollo, GraphiQL)	Medium (grpcurl, Evans)
Learning curve	Low (~2 days)	Medium (~6 days)	High (~7+ days; Protobuf toolchain)
Browser-friendly	Yes	Yes	No (gRPC-web proxy needed)
Streaming	SSE / chunked transfer	Subscriptions	Native bidirectional
Latency	~250ms median	~180ms complex queries	~25ms equivalent queries

Decision heuristic:

• Public API, third-party clients → REST (reach, caching, tooling)
• Internal graph with many consumer shapes, N+1 round-trip problem → GraphQL
• Internal service-to-service, high-throughput or streaming → gRPC
• LLM/agentic interface → see agentic-interface-design

Commonly Misused HTTP Status Codes

Code	Correct use	Common mistake
400	Request is malformed (bad JSON, missing required field)	Used for business logic errors (use 422)
401	Not authenticated (no token or invalid token)	Confused with 403
403	Authenticated but not authorized	Used when 404 is safer (don't leak resource existence)
404	Resource not found	Overused for authorization
409	Conflict (duplicate key, concurrent edit)	Underused — should be used more often
422	Semantically invalid (passes syntax, fails business validation)	Conflated with 400
429	Rate limited	Missing Retry-After header — always required with 429
202	Accepted for async processing	Used when work is synchronous (use 200 or 201)

Postel's Law — Use with Caution

"Be liberal in what you accept, be conservative in what you send" was designed for TCP bootstrapping — not API design. Modern critique (CACM, RFC on Robustness Principle Reconsidered):

• Permissive acceptance entrenches bugs as de facto standards
• Creates security vulnerabilities (overly permissive parsers are attack surfaces)
• Complicates future evolution (anything accepted becomes load-bearing)

Practical stance for new APIs: be conservative on both sides. Accept precisely what the schema documents; return precisely what is documented. Reserve liberal acceptance for legacy interoperability you cannot control.

When to Reach for Which Reference

Task	Reference file
Study the canonical APIs and standards in depth	api-canon.md
REST quality patterns (status codes, PATCH, webhooks, versioning)	rest-patterns.md
GraphQL quality patterns (Relay, errors in type system, DataLoader)	graphql-patterns.md
gRPC quality patterns (Protobuf design, FieldMask, streaming modes)	grpc-patterns.md
Latency: N+1, caching, streaming, payload shape	low-latency-ergonomics.md
Reviewing an API design	design-review-checklist.md
Shared design principles (Rams, Norman, Nielsen, Bloch)	design-fundamentals.md

Related Skills

• api-design — the methodology layer: API-first process, resource modeling, OpenAPI spec patterns, versioning strategies, interface contracts. This skill is the quality lens; api-design is the how-to.
• agentic-interface-design — the same quality/taste lens applied to MCP tools, function-calling schemas, and A2A contracts (the model as consumer).
• external-api-docs — for verifying current API specifications, SDK versions, or library capabilities before committing to a paradigm decision.
• data-modeling — backend schema design informs resource modeling; when the resource model feels wrong, often the data model is the root cause.
• performance-architecture — infrastructure-level performance behind the API surface; this skill covers interface-level latency ergonomics.
• api-documentation — turning the reviewed API into best-in-class human + agent docs (the doc-production deliverable downstream of the design critique).