/api-design

name: api-design
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "API wire contracts for REST and GraphQL: resource shape, versioning and deprecation, RFC 9457 errors, OpenAPI. Use when designing an endpoint contract. Not for runtime code (use python-backend)."
user-invocable: false
disable-model-invocation: false
metadata:
  owner-agent: "backend-system-architect"
  category: document-asset-creation
  version: "2.0.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "api-design, rest, graphql, versioning, error-handling, rfc9457, openapi, problem-details"
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 (`/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