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.
Provides API design patterns for REST, GraphQL, versioning, and RFC 9457 error handling.
/plugin marketplace add yonatangross/orchestkit/plugin install orkl@orchestkitThis skill inherits all available tools. When active, it can use any tool Claude has access to.
assets/asyncapi-template.yamlassets/openapi-template.yamlchecklists/api-design-checklist.mdchecklists/error-handling-checklist.mdchecklists/versioning-checklist.mdexamples/fastapi-problem-details.mdexamples/fastapi-versioning.mdexamples/orchestkit-api-design.mdmetadata.jsonreferences/frontend-integration.mdreferences/graphql-api.mdreferences/grpc-api.mdreferences/payload-access-control.mdreferences/payload-collection-design.mdreferences/payload-vs-sanity.mdreferences/rest-api.mdreferences/rest-patterns.mdreferences/rfc9457-spec.mdreferences/telegram-bot-api.mdreferences/versioning-strategies.mdComprehensive 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 | 3 | HIGH | RFC 9457 Problem Details, 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: 17 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 |
| 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: validation, field error, 422, unprocessable, pydantic Solves:
Keywords: error registry, problem types, error catalog, error codes Solves:
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.