Use this skill when designing APIs, choosing between REST/GraphQL/gRPC, writing OpenAPI specs, implementing pagination, versioning endpoints, or structuring request/response schemas. Triggers on API design, endpoint naming, HTTP methods, status codes, rate limiting, authentication schemes, HATEOAS, query parameters, and any task requiring API architecture decisions.
Use this skill when designing APIs, choosing between REST/GraphQL/gRPC, writing OpenAPI specs, implementing pagination, versioning endpoints, or structuring request/response schemas. Triggers on API design, endpoint naming, HTTP methods, status codes, rate limiting, authentication schemes, HATEOAS, query parameters, and any task requiring API architecture decisions.
When this skill is activated, always start your first response with the 🧢 emoji.
API Design
API design is the practice of defining the contract between a service and its
consumers in a way that is consistent, predictable, and resilient to change.
A well-designed API reduces integration friction, makes versioning safe, and
communicates intent through naming and structure rather than documentation alone.
This skill covers the three dominant paradigms - REST, GraphQL, and gRPC - along
with OpenAPI specs, pagination strategies, versioning, error formats, and
authentication patterns.
When to use this skill
Trigger this skill when the user:
Asks how to name, structure, or version API endpoints
Needs to choose between REST, GraphQL, or gRPC for a new service
Wants to write or review an OpenAPI / Swagger specification
Asks about HTTP status codes and when to use each
Needs to implement pagination (offset, cursor, keyset)
Asks about authentication schemes (API key, OAuth2, JWT)
Wants a consistent error response format across their API
Needs to design request/response schemas or query parameters
Do NOT trigger this skill for:
Internal function/method interfaces inside a single service - use clean-code or clean-architecture skills
Database schema design unless it is driven by API contract requirements
Key principles
Consistency over cleverness - Every endpoint, field name, error shape, and
status code should follow the same pattern throughout the API. Consumers should
be able to predict behavior for an endpoint they have never used before.
Resource-oriented design - Model your API around nouns (resources), not
verbs (actions). POST /orders is better than POST /createOrder. The HTTP
method carries the verb.
Proper HTTP semantics - Use the right method (GET is safe + idempotent,
PUT/DELETE are idempotent, POST is neither). Use correct status codes:
201 for creation, 204 for empty success, 400 for client errors, 404
for not found, 409 for conflicts, 429 for rate limiting.
Version from day one - Include a version in your URL or header before
publishing. in the path costs nothing; removing a breaking change from
a production API costs everything.
v1
Design for the consumer - Shape responses around what the client needs, not
around what the database returns. Clients should not have to join, filter, or
transform data after receiving a response.
Core concepts
REST resources
REST treats everything as a resource identified by a URL. Resources are
manipulated through a uniform interface: GET, POST, PUT, PATCH, DELETE.
Collections live at /resources and individual items at /resources/{id}.
Sub-resources express ownership: /users/{id}/orders.
GraphQL schema
GraphQL exposes a single endpoint and lets clients declare exactly which fields
they need. The schema is the contract - it defines types, queries, mutations, and
subscriptions. Best for: UIs that need flexible data fetching, aggregating multiple
back-end services, or reducing over/under-fetching.
gRPC + Protobuf
gRPC uses Protocol Buffers as its IDL and HTTP/2 as transport. It generates
strongly-typed client/server stubs. Best for: internal service-to-service
communication where performance, type safety, and streaming matter more than
browser compatibility.
When to use which
Need
REST
GraphQL
gRPC
Public/partner API
Best
Good
Avoid
Browser clients
Best
Best
Poor
Internal microservices
Good
Overkill
Best
Real-time / streaming
Polling/SSE
Subscriptions
Best
Flexible field selection
Sparse fieldsets
Best
N/A
Type-safe contracts
OpenAPI
Schema
Proto
Common tasks
1. Design RESTful resource endpoints
Use lowercase, hyphen-separated plural nouns. Never use verbs in the path.
# Collections
GET /v1/articles - list
POST /v1/articles - create
# Single resource
GET /v1/articles/{id} - read
PUT /v1/articles/{id} - full replace
PATCH /v1/articles/{id} - partial update
DELETE /v1/articles/{id} - delete
# Sub-resources
GET /v1/users/{id}/orders - list orders for a user
# Actions that don't map to CRUD (use verb noun under resource)
POST /v1/orders/{id}/cancel
POST /v1/users/{id}/password-reset
2. Write an OpenAPI 3.1 spec
Always use $ref to pull components out of paths for reuse. See
references/openapi-patterns.md for the full component library (security
schemes, reusable responses, discriminators, webhooks).
Recommendation: URL path versioning for public APIs (/v1/, /v2/), header
versioning for internal/partner APIs. Avoid query param versioning - it leaks into
caches and logs.
Decision rule: Start with REST. Move to GraphQL when UI teams are blocked by
over/under-fetching. Move to gRPC for high-throughput internal services where
latency and type safety are critical.
Error handling reference
Scenario
Status Code
Successful creation
201 Created
Successful with no body
204 No Content
Bad request / malformed JSON
400 Bad Request
Missing or invalid auth token
401 Unauthorized
Valid token, insufficient permission
403 Forbidden
Resource not found
404 Not Found
HTTP method not allowed
405 Method Not Allowed
Conflict (duplicate, stale update)
409 Conflict
Validation errors on input
422 Unprocessable Entity
Rate limit exceeded
429 Too Many Requests
Unexpected server error
500 Internal Server Error
Upstream dependency unavailable
503 Service Unavailable
Gotchas
Offset pagination breaks under concurrent writes - Offset-based pagination (?page=2&limit=20) produces incorrect results when rows are inserted or deleted between pages. Use cursor-based pagination (keyset/seek) for any dataset that changes while clients are paginating through it.
Breaking changes in "minor" updates - Removing a field, changing a field's type, or narrowing an enum are breaking changes even if you don't bump the version. Consumers fail at runtime with no warning. Use the expand-contract pattern: add the new field, deprecate the old one, remove it only after all consumers have migrated.
422 vs 400 confusion - 400 Bad Request is for malformed requests (unparseable JSON, wrong content type). 422 Unprocessable Entity is for syntactically valid requests that fail business validation (email already taken, negative quantity). Returning 400 for validation errors prevents consumers from distinguishing parse errors from validation failures.
URL versioning leaks into caches and logs - Query parameter versioning (?version=2) gets cached incorrectly by HTTP caches that ignore query strings, and pollutes analytics logs. URL path versioning (/v2/) is cleanest for public APIs; header versioning is better for internal APIs that need per-consumer negotiation.
DELETE returning 200 with a body vs 204 - Many clients discard the body on 204 No Content responses. If you need to return data from a delete operation, use 200 OK with a body. If nothing needs to be returned, use 204. Mixing them creates client parsing bugs.
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
