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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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.
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.
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
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.
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
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)
