nmor/the-claude-council/api-design

Claude Code and agent skill by nmor/the-claude-council

Trust tier 3
  • community
Source check pending

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-design

SKILL.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.

TopicRead
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 — proto files are the contract
  • Webhook-only outbound interfaces — see ~/.claude/rules-library/common/api-versioning.md for

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 — Sunset HTTP header for deprecation
  • RFC 8288 — Web Linking (Link header 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

PatternWhy badCorrect alternative
200 OK with success: false bodyLoses HTTP semantics; generic middleware (CDN, load balancer, retry logic) can't branchMap 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 actionGET /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-KeyDouble-charge / double-create on network retryAccept Idempotency-Key header (Stripe pattern) — see ~/.claude/rules-library/common/idempotency.md
201 Created without Location headerClient doesn't know the new resource URLAlways set Location: /api/v1/<resource>/<id>
Major version bump for additive changes (new optional field)Forces unnecessary client migration; burns version slotsAdditive = same major; only breaking = bump
Offset pagination on tables with concurrent writesItems shift between pages → duplicates and gapsCursor pagination over indexed column
Server stack traces leaking through error bodyReveals framework, version, file paths to attackersStrip 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 + optional details[]; no internal

stack traces

  • [ ] List endpoints paginated (cursor preferred); response includes meta.next_cursor or

meta.total

  • [ ] POST returns 201 Created + Location header
  • [ ] Idempotency-Key supported on mutating POSTs (per

~/.claude/rules-library/common/idempotency.md)

  • [ ] Versioning via URL path (/api/v1/) OR Accept header; deprecation signalled via Sunset +

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-Key contract
  • ~/.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 OK becomes 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.md violation)
  • Pagination missing on a list endpoint (page, limit, total, next_cursor absent)
  • Versioning omitted on public API (sister api-versioning.md violation)
  • Idempotency key not accepted on a POST mutation (sister idempotency.md violation)
  • Rate-limit headers (RateLimit-*, Retry-After) absent on a public endpoint
  • Response shape evolves without contract test (sister contract-testing.md violation)
  • as cast hiding shape drift between BE + FE (sister S6571 + no-discards.md rule 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.md
  • rules-library/common/api-versioning.md
  • rules-library/common/contract-testing.md
  • rules-library/common/schema-evolution.md
  • rules-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

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
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/nmor/the-claude-council/api-design/badge)](https://verified-skill.com/skills/nmor/the-claude-council/api-design)

Something wrong with this skill or its page? Tell us.