/api-design

name: api-design
license: MIT
compatibility: "Claude Code 2.1.220+."
description: 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.
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.*"]

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](#api-framework) | 3 | HIGH | REST conventions, resource modeling, OpenAPI specifications | | [Versioning](#versioning) | 2 | HIGH | URL path versioning, header versioning; deprecation windows are house policy in `references/ork-delta.md` | | [Error Handling](#error-handling) | 1 | HIGH | Agent-facing RFC 9457 extensions; base spec and FastAPI wiring are upstream | | [GraphQL](#graphql) | 2 | HIGH | Strawberry code-first, DataLoader, permissions, subscriptions | | [gRPC](#grpc) | 2 | HIGH | Protobuf services, streaming, interceptors, retry | | [Streaming](#streaming) | 2 | HIGH | SSE endpoints, WebSocket bidirectional, async generators | | [Integrations](#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](#upstream-coverage-do-not-restate)).

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](#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`.

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 (`/ap