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