메뉴
API design patterns for REST/GraphQL framework design, versioning strategies, and RFC 9457 error handling. Use when designing API endpoints, choosing versioning schemes, implementing Problem Details errors, or building OpenAPI specifications.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | api-design |
| license | MIT |
| compatibility | Claude Code 2.1.183+. |
| description | API design patterns for REST/GraphQL framework design, versioning strategies, and RFC 9457 error handling. Use when designing API endpoints, choosing versioning schemes, implementing Problem Details errors, or building OpenAPI specifications. |
| tags | ["api-design","rest","graphql","versioning","error-handling","rfc9457","openapi","problem-details"] |
| context | fork |
| agent | backend-system-architect |
| version | 2.0.0 |
| author | OrchestKit |
| user-invocable | false |
| disable-model-invocation | false |
| complexity | medium |
| persuasion-type | reference |
| metadata | {"category":"document-asset-creation"} |
| allowed-tools | ["Read","Glob","Grep","WebFetch","WebSearch"] |
| path_patterns | ["**/routes/**","**/api/**","**/endpoints/**","openapi.*","swagger.*"] |
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.
| Category | Rules | Impact | When to Use |
|---|---|---|---|
| API Framework | 3 | HIGH | REST conventions, resource modeling, OpenAPI specifications |
| Versioning | 3 | HIGH | URL path versioning, header versioning, deprecation/sunset policies |
| Error Handling | 4 | HIGH | RFC 9457 Problem Details, agent-facing errors, validation errors, error type registries |
| 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: 18 rules across 7 categories
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 |
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 | rules/versioning-deprecation.md | Sunset headers, lifecycle management, breaking change policy |
RFC 9457 Problem Details for machine-readable, standardized error responses.
| Rule | File | Key Pattern |
|---|---|---|
| Problem Details | rules/errors-problem-details.md | RFC 9457 schema, application/problem+json, exception classes |
| Agent-Facing Errors | rules/errors-agent-facing.md | Agent extensions: retryable, error_category, content negotiation, token efficiency |
| Validation | rules/errors-validation.md | Field-level errors, Pydantic integration, 422 responses |
| Error Catalog | rules/errors-error-catalog.md | Problem type registry, error type URIs, client handling |
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 |
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 |
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 |
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 |
# 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)
| 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 |
POST /createUser instead of POST /users)Content-Type: application/problem+json on error responsesSee test-cases.json for 9 test cases across all categories.
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 APIsKeywords: rest, restful, http, endpoint, route, path, resource, CRUD Solves:
Keywords: graphql, schema, query, mutation, connection, relay Solves:
Keywords: endpoint, route, path, resource, CRUD, openapi Solves:
Keywords: url version, path version, /v1/, /v2/ Solves:
Keywords: header version, X-API-Version, content negotiation Solves:
Keywords: deprecation, sunset, version lifecycle, backward compatible Solves:
Keywords: problem details, RFC 9457, RFC 7807, structured error, application/problem+json Solves:
Keywords: agent error, AI agent, retryable, retry_after, error_category, content negotiation, accept header, token efficient, machine readable Solves:
Keywords: validation, field error, 422, unprocessable, pydantic Solves:
Keywords: error registry, problem types, error catalog, error codes Solves:
OrchestKit doctor for health diagnostics across manifest integrity, hook configuration, skill validation, agent frontmatter, MCP server connectivity, CC version compatibility, and permission rules. Reports issues with severity levels and auto-remediation suggestions. Validates component counts, detects orphaned entries, and checks CC version matrix compliance. Use when diagnosing plugin health, troubleshooting configuration issues, or running pre-release checks.
Interactive MCP visual output via @json-render/mcp. Upgrade plain JSON tool responses to interactive dashboards rendered in sandboxed iframes inside Claude, Cursor, ChatGPT, VS Code Copilot, Goose, and Postman conversations. Covers createMcpApp(), registerJsonRenderTool(), registerJsonRenderResource(), CSP config, JSON Patch streaming, and dashboard component patterns. Use when building MCP servers that return visual output, upgrading existing MCP tools with interactive UI, or creating eval/monitoring dashboards.
Multi-surface rendering with json-render — same JSON spec produces React web, Next.js apps, React Native, Ink terminal UIs, PDFs, emails, Remotion videos, OG images, and 3D scenes. Covers renderer target selection, registry mapping, and platform-specific APIs (renderToBuffer, renderToStream, renderToFile). Use when generating output for multiple platforms, creating PDF reports, email templates, demo videos, or social media images from a single component spec.
Validates hook, skill, and agent counts are consistent across CLAUDE.md, hooks.json, manifests, and source directories. Use when counts may be stale after adding or removing components, before releases, or when CLAUDE.md Project Overview looks wrong.
OrchestKit security wrapper for browser automation. Adds URL blocklisting, rate limiting, robots.txt enforcement, and ethical scraping guardrails on top of the upstream agent-browser skill. Use when automating browser workflows that need safety guardrails.
One-command dev loop boot. Spins up portless (named HTTPS subdomain), emulate (stateful API mocks), the project's dev server, and an agent-browser session — all using the current git branch as the namespace key. Replaces the 4-terminal manual setup with a single `/ork:dev` invocation. Use when starting a new feature branch, switching worktrees, or returning to a project after a break. Skip silently when prerequisite binaries (portless, emulate, agent-browser) are missing — emits install hints.