nmor/the-claude-council/api-design
Claude Code and agent skill by nmor/the-claude-council
- community
Checking that the SKILL.md file is still in the repository.
REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs. Also lazy-loads api-versioning.md / contract-testing.md / schema-evolution.md / deprecation-lifecycle.md content migrated from rules/common/ on 2026-06-02.
Install
npx vskill@latest install nmor/the-claude-council/api-designSKILL.md
The same SKILL.md was published earlier as nmor/the-claude-council/api-design.
API Design Patterns
Size budget: 25 KB. Check: wc -c. Gate: node ~/.claude/scripts/token-budget.mjs --check
Conventions and best practices for designing consistent, developer-friendly REST APIs.
When to Activate
- Designing new API endpoints
- Reviewing existing API contracts
- Adding pagination, filtering, or sorting
- Implementing error handling for APIs
- Planning API versioning strategy
- Building public or partner-facing APIs
Routing table
This skill is paths:-gated: when a glob above matches, this file is added to the always-on context in full. It is therefore a ROUTER. The detail lives in references/; read the row you need, not the whole set.
| Topic | Read | |
|---|---|---|
| Resource design + HTTP methods / status codes — URL structure, naming rules, method semantics table, status-code reference, common mistakes | `references/rest-conventions.md` | |
| Response format + error envelope — success, collection, error bodies, envelope variants | `references/response-format.md` | |
| Pagination, filtering, sorting, search — offset vs cursor (+ when to use which), filter/sort/search syntax, sparse fieldsets | `references/pagination-filtering.md` | |
Authentication, authorization, rate limiting — bearer/API key, ownership + role checks, RateLimit-* headers, tier table | `references/auth-and-rate-limits.md` | |
| Implementation examples — TypeScript (Next.js), Python (DRF), Go (net/http) handlers | `references/implementation-examples.md` | |
| Response-shape contracts (BE/FE drift) — the empty-not-broken bug class, the shared-type + pinned-test contract, endpoint-change workflow | `references/response-shape-contracts.md` | |
Versioning — strategies, breaking vs additive, tolerant reader, parallel versions, Sunset/Deprecation headers, GraphQL + gRPC specifics, SDK versioning | `references/api-versioning.md` | |
| Contract testing — CDC (Pact) vs schema-based (OpenAPI/GraphQL/Proto), deploy gating, per-stack examples | `references/contract-testing.md` | |
| Schema evolution — compatibility modes, expand-contract, zero-downtime DDL, backfills, per-store specifics (PG/MySQL/Mongo/DynamoDB/Kafka) | `references/schema-evolution.md` | |
Deprecation lifecycle — the four stages + calendar minimums, per-language @deprecated patterns, HTTP deprecation headers | `references/deprecation-lifecycle.md` | |
API design standards (endpoint checklist + skill chain) — the migrated rules-library/common/api-design.md | `references/api-design-standards.md` |
API Design Checklist
Before shipping a new endpoint:
- [ ] Resource URL follows naming conventions (plural, kebab-case, no verbs)
- [ ] Correct HTTP method used (GET for reads, POST for creates, etc.)
- [ ] Appropriate status codes returned (not 200 for everything)
- [ ] Input validated with schema (Zod, Pydantic, Bean Validation)
- [ ] Error responses follow standard format with codes and messages
- [ ] Pagination implemented for list endpoints (cursor or offset)
- [ ] Authentication required (or explicitly marked as public)
- [ ] Authorization checked (user can only access their own resources)
- [ ] Rate limiting configured
- [ ] Response does not leak internal details (stack traces, SQL errors)
- [ ] Consistent naming with existing endpoints (camelCase vs snake_case)
- [ ] Documented (OpenAPI/Swagger spec updated)
- [ ] Response shape pinned by a shared type AND a contract test (see "Response-shape contracts"
below)
Purpose
Design REST API contracts that are consistent, predictable, and stable across versions. Covers resource naming, status codes, pagination, filtering, error envelopes, authentication shape, rate-limit semantics, and response-shape contracts between backend and frontend.
Negative scope: NOT GraphQL schema design (GraphQL evolves additively at field level, not URL level). NOT internal RPC contracts (gRPC / Proto live under their own discipline). NOT message-bus event schemas (Kafka / SNS contracts are the event payload, not a REST surface). NOT internal-only DB-backed handlers with no external consumer.
When NOT to use
- GraphQL services — schema-level evolution rules differ; use a GraphQL-specific guide
- gRPC / Proto3 services —
protofiles are the contract - Webhook-only outbound interfaces — see
~/.claude/rules-library/common/api-versioning.mdfor
sunset semantics
- Pure event-driven systems (Kafka, SNS, EventBridge) where the contract is the event schema
- Throw-away admin scripts with a single internal caller
Standards Cited
- RFC 9110 (HTTP Semantics, Jun 2022) §15.5 (Client Error 4xx) + §15.6 (Server Error 5xx) —
status code semantics
- RFC 9110 §9.2.2 — Idempotent methods (PUT, DELETE, GET, HEAD, OPTIONS)
- RFC 9457 (Problem Details for HTTP APIs, Jul 2023) — standardised error response shape
- RFC 8594 —
SunsetHTTP header for deprecation - RFC 8288 — Web Linking (
Linkheader for pagination + relations) - RFC 6585 §4 —
429 Too Many Requests - OWASP ASVS 4.0.3 §13.1 (Generic Web Service Security) + §13.2.5 (HTTP method allowlist)
- OWASP API Security Top 10 (2023) API1 (BOLA), API4 (Unrestricted Resource Consumption), API9
(Improper Inventory Management)
Anti-Patterns
| Pattern | Why bad | Correct alternative | |
|---|---|---|---|
200 OK with success: false body | Loses HTTP semantics; generic middleware (CDN, load balancer, retry logic) can't branch | Map outcome to status — 4xx client, 5xx server per RFC 9110 §15 | |
Verb in URL (/getUsers, /createOrder) | REST URLs are nouns; the HTTP verb is the action | GET /users, POST /orders | |
| Exposing DB primary keys (auto-incrementing IDs) | Enumeration leaks customer count + enables IDOR (OWASP API1) | UUIDs / ULIDs / opaque encoded IDs | |
Non-idempotent POST without Idempotency-Key | Double-charge / double-create on network retry | Accept Idempotency-Key header (Stripe pattern) — see ~/.claude/rules-library/common/idempotency.md | |
201 Created without Location header | Client doesn't know the new resource URL | Always set Location: /api/v1/<resource>/<id> | |
| Major version bump for additive changes (new optional field) | Forces unnecessary client migration; burns version slots | Additive = same major; only breaking = bump | |
| Offset pagination on tables with concurrent writes | Items shift between pages → duplicates and gaps | Cursor pagination over indexed column | |
| Server stack traces leaking through error body | Reveals framework, version, file paths to attackers | Strip at boundary; error.code + error.message only |
Verification Checklist
- [ ] Status codes match RFC 9110 (404 missing, 409 conflict, 422 unprocessable, 429 rate-limit)
- [ ] Error envelope has stable
error.code+error.message+ optionaldetails[]; no internal
stack traces
- [ ] List endpoints paginated (cursor preferred); response includes
meta.next_cursoror
meta.total
- [ ] POST returns
201 Created+Locationheader - [ ]
Idempotency-Keysupported on mutating POSTs (per
~/.claude/rules-library/common/idempotency.md)
- [ ] Versioning via URL path (
/api/v1/) OR Accept header; deprecation signalled viaSunset+
Link: rel="successor-version"
- [ ] Rate-limit headers (
RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset) on every
endpoint
- [ ] Response shape pinned by shared type AND a contract test (per Response-shape contracts above)
- [ ] OWASP API Top 10 cross-check (BOLA on every object-level read, rate-limit on every public
endpoint)
Cross-References
~/.claude/rules-library/common/api-versioning.md— major-vs-minor evolution rules +Sunset
lifecycle
~/.claude/rules-library/common/idempotency.md—Idempotency-Keycontract~/.claude/rules-library/common/error-handling-with-context.md— error envelope shape
(operation + ids)
~/.claude/rules-library/common/error-codes.md— stable code catalogue~/.claude/rules-library/common/rate-limiting.md— RateLimit-* header standard~/.claude/rules-library/common/contract-testing.md— CDC (Pact) + OpenAPI / JSON Schema
validation
~/.claude/skills/backend-patterns/SKILL.md— handler / middleware patterns~/.claude/agents/security-reviewer.md— OWASP API Top 10 review
Why this skill exists
REST APIs are the most-touched public contract any product ships. Every customer integration depends on URL shape, status semantics, error structure, and pagination behaviour. The recurring failure modes are mechanical and expensive:
- Status codes drift (
200 OKbecomes the universal envelope) → generic clients break, CDN-level
retry logic mis-fires, error-rate alerting wrong
- Error shapes diverge per handler → frontend can't write one error handler → every screen ships its
own
- Pagination breaks under writes → page 2 has rows from page 1 → users see duplicates, support
tickets surge
- Version bumps land too eagerly (forced consumer work for additive change) or too late (breaking
change inside a "minor")
- Primary keys leaked → IDOR exposure + customer enumeration on a public list endpoint
Each of these costs migration weeks across N consumers when the API has integrations. Cost of correct design at write-time: one design review. Cost of redesign with integrators in flight: quarters.
Learning hooks
Per ~/.claude/rules/common/continuous-learning-mandate.md:
Signals to watch:
- Verb-based endpoint (
/getUsers,/createOrder) introduced (REST naming weakening) - HTTP status code mismatched to outcome (validation failure as 400 not 422, create as 200 not 201)
- Error envelope differs between handlers (consistency drift — sister
error-codes.mdviolation) - Pagination missing on a list endpoint (
page,limit,total,next_cursorabsent) - Versioning omitted on public API (sister
api-versioning.mdviolation) - Idempotency key not accepted on a POST mutation (sister
idempotency.mdviolation) - Rate-limit headers (
RateLimit-*,Retry-After) absent on a public endpoint - Response shape evolves without contract test (sister
contract-testing.mdviolation) ascast hiding shape drift between BE + FE (sister S6571 +no-discards.mdrule 8)
Refinement candidates:
- New endpoint-class row when a recurring shape emerges (e.g., webhook receivers, SSE streams, gRPC
unary, GraphQL mutation)
- Tightening of the response-envelope contract when sister rules (
error-codes.md,
error-handling-with-context.md) evolve
- New cross-reference when a sister skill (security-review, observability-patterns) adds an
endpoint-level gate
- New versioning template when a recurring breaking-change pattern emerges (e.g., field rename, enum
addition)
<!-- ============================================================ Migration appendix: 2026-06-02 lazy-rules-loading ============================================================ -->
Migrated rules (2026-06-02)
The following rules were migrated from ~/.claude/rules/common/ into this skill as part of the lazy-rules-loading plan. Phase H will delete the source files.
rules-library/common/api-design.mdrules-library/common/api-versioning.mdrules-library/common/contract-testing.mdrules-library/common/schema-evolution.mdrules-library/common/deprecation-lifecycle.md
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/api-design/SKILL.md
Popularity
- 7-day trend score
- 5
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/nmor/the-claude-council/api-design)