API Design
Comprehensive API design patterns covering REST/GraphQL framework design, versioning strategies, and RFC 9457 error handling. Each category has individual rule files in rules/ loaded on-demand.
Quick Reference
| Category |
Rules |
Impact |
When to Use |
| API Framework |
3 |
HIGH |
REST conventions, resource modeling, OpenAPI specifications |
| Versioning |
2 |
HIGH |
URL path versioning, header versioning; deprecation windows are house policy in references/ork-delta.md |
| Error Handling |
1 |
HIGH |
Agent-facing RFC 9457 extensions; base spec and FastAPI wiring are upstream |
| GraphQL |
2 |
HIGH |
Strawberry code-first, DataLoader, permissions, subscriptions |
| gRPC |
2 |
HIGH |
Protobuf services, streaming, interceptors, retry |
| Streaming |
2 |
HIGH |
SSE endpoints, WebSocket bidirectional, async generators |
| Integrations |
2 |
HIGH |
Messaging platforms (WhatsApp, Telegram), Payload CMS patterns |
Total: 14 rules across 7 categories. House decisions rescued from thinned files live in references/ork-delta.md; vendor and spec material is linked, not restated (see Upstream coverage).
API Framework
REST and GraphQL API design conventions for consistent, developer-friendly APIs.
| Rule |
File |
Key Pattern |
| REST Conventions |
rules/framework-rest-conventions.md |
Plural nouns, HTTP methods, status codes, pagination |
| Resource Modeling |
rules/framework-resource-modeling.md |
Hierarchical URLs, filtering, sorting, field selection |
| OpenAPI |
rules/framework-openapi.md |
OpenAPI 3.1 specs, documentation, schema definitions |
Versioning
Strategies for API evolution without breaking clients.
| Rule |
File |
Key Pattern |
| URL Path |
rules/versioning-url-path.md |
/api/v1/ prefix routing, version-specific schemas |
| Header |
rules/versioning-header.md |
X-API-Version header, content negotiation |
Deprecation and sunset: the house window (3 months notice, 6 months sunset, current + 1 supported) is in references/ork-delta.md; header mechanics are upstream (RFC 8594, RFC 9745).
Error Handling
RFC 9457 Problem Details for machine-readable, standardized error responses.
| Rule |
File |
Key Pattern |
| Agent-Facing Errors |
rules/errors-agent-facing.md |
Agent extensions: retryable, error_category, content negotiation, token efficiency |
The RFC 9457 base format, FastAPI exception-handler wiring, and Pydantic 422 mapping are upstream (see Upstream coverage). The house pieces survive here: problem type URI convention and typed exception vocabulary in references/ork-delta.md, full working implementation in examples/fastapi-problem-details.md.
GraphQL
Strawberry GraphQL code-first schema with type-safe resolvers and FastAPI integration.
| Rule |
File |
Key Pattern |
| Schema Design |
rules/graphql-strawberry.md |
Type-safe schema, DataLoader, union errors, Private fields |
| Patterns & Auth |
rules/graphql-schema.md |
Permission classes, FastAPI integration, subscriptions |
gRPC
High-performance gRPC for internal microservice communication.
| Rule |
File |
Key Pattern |
| Service Definition |
rules/grpc-service.md |
Protobuf, async server, client timeout, code generation |
| Streaming & Interceptors |
rules/grpc-streaming.md |
Server/bidirectional streaming, auth, retry backoff |
Streaming
Real-time data streaming with SSE, WebSockets, and proper cleanup.
| Rule |
File |
Key Pattern |
| SSE |
rules/streaming-sse.md |
SSE endpoints, LLM streaming, reconnection, keepalive |
| WebSocket |
rules/streaming-websocket.md |
Bidirectional, heartbeat, aclosing(), backpressure |
Integrations
Messaging platform integrations and headless CMS patterns.
| Rule |
File |
Key Pattern |
| Messaging Platforms |
rules/messaging-integrations.md |
WhatsApp WAHA, Telegram Bot API, webhook security |
| Payload CMS |
rules/payload-cms.md |
Payload 3.0 collections, access control, CMS selection |
Quick Start Example
# REST endpoint with versioning and RFC 9457 errors
from fastapi import APIRouter, Depends, Request
from fastapi.responses import JSONResponse
router = APIRouter()
@router.get("/api/v1/users/{user_id}")
async def get_user(user_id: str, service: UserService = Depends()):
user = await service.get_user(user_id)
if not user:
raise NotFoundProblem(
resource="User",
resource_id=user_id,
)
return UserResponseV1(id=user.id, name=user.full_name)
Key Decisions
| Decision |
Recommendation |
| Versioning strategy |
URL path (/api/v1/) for public APIs |
| Resource naming |
Plural nouns, kebab-case |
| Pagination |
Cursor-based for large datasets |
| Error format |
RFC 9457 Problem Details with application/problem+json |
| Error type URI |
Your API domain + /problems/ prefix |
| Support window |
Current + 1 previous version |
| Deprecation notice |
3 months minimum before sunset |
| Sunset period |
6 months after deprecation |
| GraphQL schema |
Code-first with Strawberry types |
| N+1 prevention |
DataLoader for all nested resolvers |
| GraphQL auth |
Permission classes (context-based) |
| gRPC proto |
One service per file, shared common.proto |
| gRPC streaming |
Server stream for lists, bidirectional for real-time |
| SSE keepalive |
Every 30 seconds |
| WebSocket heartbeat |
ping-pong every 30 seconds |
| Async generator cleanup |
aclosing() for all external resources |
Common Mistakes
- Verbs in URLs (
POST /createUser instead of POST /users)
- Inconsistent error formats across endpoints
- Breaking contracts without version bump
- Plain text error responses instead of Problem Details
- Sunsetting versions without deprecation headers
- Exposing internal details (stack traces, DB errors) in errors
- Missing
Content-Type: application/problem+json on error responses
- Supporting too many concurrent API versions (max 2-3)
- Caching without considering version isolation
Upstream coverage (do not restate)
Topics removed in the 2026-07-31 wrap-plus-delta thinning. Consult the first-party source; only the ork delta (house policy, scars, working config) belongs in this skill.
| Topic |
First-party source |
RFC 9457 Problem Details spec (members, media type, about:blank, client parsing) |
https://www.rfc-editor.org/rfc/rfc9457.html |
| FastAPI exception handlers, Pydantic validation errors (422), error catalog boilerplate |
https://fastapi.tiangolo.com/tutorial/handling-errors/ |
| API versioning strategy tutorials and FastAPI versioned-router walkthroughs |
https://fastapi.tiangolo.com/tutorial/bigger-applications/ |
| Deprecation and Sunset header mechanics |
https://www.rfc-editor.org/rfc/rfc8594.html and https://www.rfc-editor.org/rfc/rfc9745.html |
| Generic REST reference (methods, status codes, pagination shapes, auth headers) |
https://www.rfc-editor.org/rfc/rfc9110.html and https://developer.mozilla.org/en-US/docs/Web/HTTP |
OpenAPI 3.1 spec authoring (template survives in assets/openapi-template.yaml) |
https://spec.openapis.org/oas/v3.1.0 |
| gRPC proto style, service definition, status codes |
https://grpc.io/docs/ and https://protobuf.dev/programming-guides/style/ |
| Payload CMS collection design, field types, access control |
https://payloadcms.com/docs |
| Frontend API consumption (Zod boundary validation, ky, TanStack Query) |
https://zod.dev and https://tanstack.com/query/latest/docs |
| API design / error handling / versioning review checklists |
Derivable from the specs above; no checklist restatement kept |
Evaluations
See test-cases.json for 13 test cases across all categories.
Related Skills
fastapi-advanced - FastAPI-specific implementation patterns
rate-limiting - Advanced rate limiting implementations and algorithms
observability-monitoring - Version usage metrics and error tracking
input-validation - Validation patterns beyond API error handling
streaming-api-patterns - SSE and WebSocket patterns for real-time APIs
Capability Details
rest-design
Keywords: rest, restful, http, endpoint, route, path, resource, CRUD
Solves:
- How do I design RESTful APIs?
- REST endpoint patterns and conventions
- HTTP methods and status codes
graphql-design
Keywords: graphql, schema, query, mutation, connection, relay
Solves:
- How do I design GraphQL APIs?
- Schema design best practices
- Connection pattern for pagination
endpoint-design
Keywords: endpoint, route, path, resource, CRUD, openapi
Solves:
- How do I structure API endpoints?
- What's the best URL pattern for this resource?
- RESTful endpoint naming conventions
url-versioning
Keywords: url version, path version, /v1/, /v2/
Solves:
- How to version REST APIs?
- URL-based API versioning
header-versioning
Keywords: header version, X-API-Version, content negotiation
Solves:
- Clean URL versioning
- Header-based API version
deprecation
Keywords: deprecation, sunset, version lifecycle, backward compatible
Solves:
- How to deprecate API versions?
- Version sunset policy
- Breaking vs non-breaking changes
problem-details
Keywords: problem details, RFC 9457, RFC 7807, structured error, application/problem+json
Solves:
- How to standardize API error responses?
- What format for API errors?
agent-facing-errors
Keywords: agent error, AI agent, retryable, retry_after, error_category, content negotiation, accept header, token efficient, machine readable
Solves:
- How to design error responses for AI agent consumers?
- How to reduce token cost of error responses?
- How to enable deterministic agent error handling?
- Content negotiation for agents vs browsers vs LLMs
validation-errors
Keywords: validation, field error, 422, unprocessable, pydantic
Solves:
- How to handle validation errors in APIs?
- Field-level error responses
error-registry
Keywords: error registry, problem types, error catalog, error codes
Solves:
- How to document all API errors?
- Error type management
1---
2name: api-design
3license: MIT
4compatibility: "Claude Code 2.1.251+."
5description: API contract design for REST and GraphQL, covering resource shape, URL and header versioning with deprecation windows, RFC 9457 Problem Details error handling, and OpenAPI specs. Use when specifying the wire contract an endpoint exposes, choosing a versioning scheme, or standardizing error response bodies across services. Framework-agnostic protocol layer, not runtime implementation.
6tags: [api-design, rest, graphql, versioning, error-handling, rfc9457, openapi, problem-details]
7context: fork
8agent: backend-system-architect
9version: 2.0.0
10author: OrchestKit
11user-invocable: false
12disable-model-invocation: false
13complexity: medium
14persuasion-type: reference
15metadata:
16 source: https://skillmd.com/skills/yonatangross/api-design
17 category: document-asset-creation
18allowed-tools:
19 - Read
20 - Glob
21 - Grep
22 - WebFetch
23 - WebSearch
24path_patterns: ["**/routes/**", "**/api/**", "**/endpoints/**", "openapi.*", "swagger.*"]
25---
26
27# API Design
28
29Comprehensive API design patterns covering REST/GraphQL framework design, versioning strategies, and RFC 9457 error handling. Each category has individual rule files in `rules/` loaded on-demand.
30
31## Quick Reference
32
33| Category | Rules | Impact | When to Use |
34|----------|-------|--------|-------------|
35| [API Framework](#api-framework) | 3 | HIGH | REST conventions, resource modeling, OpenAPI specifications |
36| [Versioning](#versioning) | 2 | HIGH | URL path versioning, header versioning; deprecation windows are house policy in `references/ork-delta.md` |
37| [Error Handling](#error-handling) | 1 | HIGH | Agent-facing RFC 9457 extensions; base spec and FastAPI wiring are upstream |
38| [GraphQL](#graphql) | 2 | HIGH | Strawberry code-first, DataLoader, permissions, subscriptions |
39| [gRPC](#grpc) | 2 | HIGH | Protobuf services, streaming, interceptors, retry |
40| [Streaming](#streaming) | 2 | HIGH | SSE endpoints, WebSocket bidirectional, async generators |
41| [Integrations](#integrations) | 2 | HIGH | Messaging platforms (WhatsApp, Telegram), Payload CMS patterns |
42
43**Total: 14 rules across 7 categories.** House decisions rescued from thinned files live in `references/ork-delta.md`; vendor and spec material is linked, not restated (see [Upstream coverage](#upstream-coverage-do-not-restate)).
44
45## API Framework
46
47REST and GraphQL API design conventions for consistent, developer-friendly APIs.
48
49| Rule | File | Key Pattern |
50|------|------|-------------|
51| REST Conventions | `rules/framework-rest-conventions.md` | Plural nouns, HTTP methods, status codes, pagination |
52| Resource Modeling | `rules/framework-resource-modeling.md` | Hierarchical URLs, filtering, sorting, field selection |
53| OpenAPI | `rules/framework-openapi.md` | OpenAPI 3.1 specs, documentation, schema definitions |
54
55## Versioning
56
57Strategies for API evolution without breaking clients.
58
59| Rule | File | Key Pattern |
60|------|------|-------------|
61| URL Path | `rules/versioning-url-path.md` | `/api/v1/` prefix routing, version-specific schemas |
62| Header | `rules/versioning-header.md` | `X-API-Version` header, content negotiation |
63
64Deprecation and sunset: the house window (3 months notice, 6 months sunset, current + 1 supported) is in `references/ork-delta.md`; header mechanics are upstream (RFC 8594, RFC 9745).
65
66## Error Handling
67
68RFC 9457 Problem Details for machine-readable, standardized error responses.
69
70| Rule | File | Key Pattern |
71|------|------|-------------|
72| Agent-Facing Errors | `rules/errors-agent-facing.md` | Agent extensions: `retryable`, `error_category`, content negotiation, token efficiency |
73
74The RFC 9457 base format, FastAPI exception-handler wiring, and Pydantic 422 mapping are upstream (see [Upstream coverage](#upstream-coverage-do-not-restate)). The house pieces survive here: problem type URI convention and typed exception vocabulary in `references/ork-delta.md`, full working implementation in `examples/fastapi-problem-details.md`.
75
76## GraphQL
77
78Strawberry GraphQL code-first schema with type-safe resolvers and FastAPI integration.
79
80| Rule | File | Key Pattern |
81|------|------|-------------|
82| Schema Design | `rules/graphql-strawberry.md` | Type-safe schema, DataLoader, union errors, Private fields |
83| Patterns & Auth | `rules/graphql-schema.md` | Permission classes, FastAPI integration, subscriptions |
84
85## gRPC
86
87High-performance gRPC for internal microservice communication.
88
89| Rule | File | Key Pattern |
90|------|------|-------------|
91| Service Definition | `rules/grpc-service.md` | Protobuf, async server, client timeout, code generation |
92| Streaming & Interceptors | `rules/grpc-streaming.md` | Server/bidirectional streaming, auth, retry backoff |
93
94## Streaming
95
96Real-time data streaming with SSE, WebSockets, and proper cleanup.
97
98| Rule | File | Key Pattern |
99|------|------|-------------|
100| SSE | `rules/streaming-sse.md` | SSE endpoints, LLM streaming, reconnection, keepalive |
101| WebSocket | `rules/streaming-websocket.md` | Bidirectional, heartbeat, aclosing(), backpressure |
102
103## Integrations
104
105Messaging platform integrations and headless CMS patterns.
106
107| Rule | File | Key Pattern |
108|------|------|-------------|
109| Messaging Platforms | `rules/messaging-integrations.md` | WhatsApp WAHA, Telegram Bot API, webhook security |
110| Payload CMS | `rules/payload-cms.md` | Payload 3.0 collections, access control, CMS selection |
111
112## Quick Start Example
113
114```python
115# REST endpoint with versioning and RFC 9457 errors
116from fastapi import APIRouter, Depends, Request
117from fastapi.responses import JSONResponse
118
119router = APIRouter()
120
121@router.get("/api/v1/users/{user_id}")
122async def get_user(user_id: str, service: UserService = Depends()):
123 user = await service.get_user(user_id)
124 if not user:
125 raise NotFoundProblem(
126 resource="User",
127 resource_id=user_id,
128 )
129 return UserResponseV1(id=user.id, name=user.full_name)
130```
131
132## Key Decisions
133
134| Decision | Recommendation |
135|----------|----------------|
136| Versioning strategy | URL path (`/api/v1/`) for public APIs |
137| Resource naming | Plural nouns, kebab-case |
138| Pagination | Cursor-based for large datasets |
139| Error format | RFC 9457 Problem Details with `application/problem+json` |
140| Error type URI | Your API domain + `/problems/` prefix |
141| Support window | Current + 1 previous version |
142| Deprecation notice | 3 months minimum before sunset |
143| Sunset period | 6 months after deprecation |
144| GraphQL schema | Code-first with Strawberry types |
145| N+1 prevention | DataLoader for all nested resolvers |
146| GraphQL auth | Permission classes (context-based) |
147| gRPC proto | One service per file, shared common.proto |
148| gRPC streaming | Server stream for lists, bidirectional for real-time |
149| SSE keepalive | Every 30 seconds |
150| WebSocket heartbeat | ping-pong every 30 seconds |
151| Async generator cleanup | aclosing() for all external resources |
152
153## Common Mistakes
154
1551. Verbs in URLs (`POST /createUser` instead of `POST /users`)
1562. Inconsistent error formats across endpoints
1573. Breaking contracts without version bump
1584. Plain text error responses instead of Problem Details
1595. Sunsetting versions without deprecation headers
1606. Exposing internal details (stack traces, DB errors) in errors
1617. Missing `Content-Type: application/problem+json` on error responses
1628. Supporting too many concurrent API versions (max 2-3)
1639. Caching without considering version isolation
164
165## Upstream coverage (do not restate)
166
167Topics removed in the 2026-07-31 wrap-plus-delta thinning. Consult the first-party source; only the ork delta (house policy, scars, working config) belongs in this skill.
168
169| Topic | First-party source |
170|-------|--------------------|
171| RFC 9457 Problem Details spec (members, media type, `about:blank`, client parsing) | https://www.rfc-editor.org/rfc/rfc9457.html |
172| FastAPI exception handlers, Pydantic validation errors (422), error catalog boilerplate | https://fastapi.tiangolo.com/tutorial/handling-errors/ |
173| API versioning strategy tutorials and FastAPI versioned-router walkthroughs | https://fastapi.tiangolo.com/tutorial/bigger-applications/ |
174| Deprecation and Sunset header mechanics | https://www.rfc-editor.org/rfc/rfc8594.html and https://www.rfc-editor.org/rfc/rfc9745.html |
175| Generic REST reference (methods, status codes, pagination shapes, auth headers) | https://www.rfc-editor.org/rfc/rfc9110.html and https://developer.mozilla.org/en-US/docs/Web/HTTP |
176| OpenAPI 3.1 spec authoring (template survives in `assets/openapi-template.yaml`) | https://spec.openapis.org/oas/v3.1.0 |
177| gRPC proto style, service definition, status codes | https://grpc.io/docs/ and https://protobuf.dev/programming-guides/style/ |
178| Payload CMS collection design, field types, access control | https://payloadcms.com/docs |
179| Frontend API consumption (Zod boundary validation, ky, TanStack Query) | https://zod.dev and https://tanstack.com/query/latest/docs |
180| API design / error handling / versioning review checklists | Derivable from the specs above; no checklist restatement kept |
181
182## Evaluations
183
184See `test-cases.json` for 13 test cases across all categories.
185
186## Related Skills
187
188- `fastapi-advanced` - FastAPI-specific implementation patterns
189- `rate-limiting` - Advanced rate limiting implementations and algorithms
190- `observability-monitoring` - Version usage metrics and error tracking
191- `input-validation` - Validation patterns beyond API error handling
192- `streaming-api-patterns` - SSE and WebSocket patterns for real-time APIs
193
194## Capability Details
195
196### rest-design
197**Keywords:** rest, restful, http, endpoint, route, path, resource, CRUD
198**Solves:**
199- How do I design RESTful APIs?
200- REST endpoint patterns and conventions
201- HTTP methods and status codes
202
203### graphql-design
204**Keywords:** graphql, schema, query, mutation, connection, relay
205**Solves:**
206- How do I design GraphQL APIs?
207- Schema design best practices
208- Connection pattern for pagination
209
210### endpoint-design
211**Keywords:** endpoint, route, path, resource, CRUD, openapi
212**Solves:**
213- How do I structure API endpoints?
214- What's the best URL pattern for this resource?
215- RESTful endpoint naming conventions
216
217### url-versioning
218**Keywords:** url version, path version, /v1/, /v2/
219**Solves:**
220- How to version REST APIs?
221- URL-based API versioning
222
223### header-versioning
224**Keywords:** header version, X-API-Version, content negotiation
225**Solves:**
226- Clean URL versioning
227- Header-based API version
228
229### deprecation
230**Keywords:** deprecation, sunset, version lifecycle, backward compatible
231**Solves:**
232- How to deprecate API versions?
233- Version sunset policy
234- Breaking vs non-breaking changes
235
236### problem-details
237**Keywords:** problem details, RFC 9457, RFC 7807, structured error, application/problem+json
238**Solves:**
239- How to standardize API error responses?
240- What format for API errors?
241
242### agent-facing-errors
243**Keywords:** agent error, AI agent, retryable, retry_after, error_category, content negotiation, accept header, token efficient, machine readable
244**Solves:**
245- How to design error responses for AI agent consumers?
246- How to reduce token cost of error responses?
247- How to enable deterministic agent error handling?
248- Content negotiation for agents vs browsers vs LLMs
249
250### validation-errors
251**Keywords:** validation, field error, 422, unprocessable, pydantic
252**Solves:**
253- How to handle validation errors in APIs?
254- Field-level error responses
255
256### error-registry
257**Keywords:** error registry, problem types, error catalog, error codes
258**Solves:**
259- How to document all API errors?
260- Error type management