dev-api-design

What this skill does

# API Development & Design — Quick Reference

Use this skill to design, implement, and document production-grade APIs (REST, GraphQL, gRPC, and tRPC). Apply it for contract design (OpenAPI), versioning/deprecation, authentication/authorization, rate limiting, pagination, error models, and developer documentation.

**Modern best practices (Jan 2026)**: HTTP semantics and cacheability (RFC 9110), Problem Details error model (RFC 9457), OpenAPI 3.1+, contract-first + breaking-change detection, strong AuthN/Z boundaries, explicit versioning/deprecation, and operable-by-default APIs (idempotency, rate limits, observability, trace context).

---

## Default Execution Checklist

- Choose an API style based on constraints (public vs internal, performance, client query flexibility).
- Define the contract first (OpenAPI or GraphQL schema; protobuf for gRPC).
- Define the error model (RFC 9457 + stable error codes + trace IDs).
- Define AuthN/AuthZ boundaries (scopes/roles/tenancy) and threat model.
- Define pagination/filter/sort for all list endpoints.
- Define rate limits/quotas, idempotency strategy (esp. POST), and retries/backoff guidance.
- Define observability (W3C Trace Context, request IDs, metrics, logs) and SLOs.
- Add contract tests + breaking-change checks in CI.
- Publish docs with examples + migration/deprecation policy.

---

## Quick Reference

| Task | Pattern/Tool | Key Elements | When to Use |
|------|--------------|--------------|-------------|
| **Design REST API** | RESTful Design | Nouns (not verbs), HTTP methods, proper status codes | Resource-based APIs, CRUD operations |
| **Version API** | URL Versioning | `/api/v1/resource`, `/api/v2/resource` | Breaking changes, client migration |
| **Paginate results** | Cursor-Based | `cursor=eyJpZCI6MTIzfQ&limit=20` | Real-time data, large collections |
| **Handle errors** | RFC 9457 Problem Details | `type`, `title`, `status`, `detail`, `errors[]` | Consistent error responses |
| **Authenticate** | JWT Bearer | `Authorization: Bearer <token>` | Stateless auth, microservices |
| **Rate limit** | Token Bucket | `X-RateLimit-*` headers, 429 responses | Prevent abuse, fair usage |
| **Document API** | OpenAPI 3.1 | Swagger UI, Redoc, code samples | Interactive docs, client SDKs |
| **Flexible queries** | GraphQL | Schema-first, resolvers, DataLoader | Client-driven data fetching |
| **High-performance** | gRPC + Protobuf | Binary protocol, streaming | Internal microservices |
| **TypeScript-first** | tRPC | End-to-end type safety, no codegen | Monorepos, internal tools |
| **AI agent APIs** | REST + MCP | Agent experience, machine-readable | LLM/agent consumption |

---

## Decision Tree: Choosing API Style

```text
User needs: [API Type]
    ├─ Public API for third parties?
    │   └─ REST with OpenAPI docs (broad compatibility)
    │
    ├─ Internal microservices?
    │   ├─ High throughput required? → **gRPC** (binary, fast)
    │   └─ Simple CRUD? → **REST** (easy to debug)
    │
    ├─ TypeScript monorepo (frontend + backend)?
    │   └─ **tRPC** (end-to-end type safety, no codegen)
    │
    ├─ Client needs flexible queries?
    │   ├─ Real-time updates? → **GraphQL Subscriptions** or **WebSockets**
    │   └─ Complex data fetching? → **GraphQL** (avoid over-fetching)
    │
    ├─ Mobile/web clients?
    │   ├─ Many entity types? → **GraphQL** (single endpoint)
    │   └─ Simple resources? → **REST** (cacheable)
    │
    ├─ AI agents consuming API?
    │   └─ REST + **MCP** wrapper (agent experience)
    │
    └─ Streaming or bidirectional?
        └─ **gRPC** (HTTP/2 streaming) or **WebSockets**
```

---

## Navigation: Core API Patterns

### RESTful API Design

**Resource:** [references/restful-design-patterns.md](references/restful-design-patterns.md)

- Resource-based URLs with proper HTTP methods (GET, POST, PUT, PATCH, DELETE)
- HTTP status code semantics (200, 201, 404, 422, 500)
- Idempotency guarantees (GET, PUT, DELETE)
- Stateless design principles
- URL structure best practices (collection vs resource endpoints)
- Nested resources and action endpoints

---

### Pagination, Filtering & Sorting

**Resource:** [references/pagination-filtering.md](references/pagination-filtering.md)

- Offset-based pagination (simple, static datasets)
- Cursor-based pagination (real-time feeds, recommended)
- Page-based pagination (UI with page numbers)
- Query parameter filtering with operators (`_gt`, `_contains`, `_in`)
- Multi-field sorting with direction (`-created_at`)
- Performance optimization with indexes

---

### Error Handling

**Resource:** [references/error-handling-patterns.md](references/error-handling-patterns.md)

- RFC 9457 Problem Details standard
- HTTP status code reference (4xx client errors, 5xx server errors)
- Field-level validation errors
- Trace IDs for debugging
- Consistent error format across endpoints
- Security-safe error messages (no stack traces in production)

---

### Authentication & Authorization

**Resource:** [references/authentication-patterns.md](references/authentication-patterns.md)

- JWT (JSON Web Tokens) with refresh token rotation
- OAuth2 Authorization Code Flow for third-party auth
- API Key authentication for server-to-server
- RBAC (Role-Based Access Control)
- ABAC (Attribute-Based Access Control)
- Resource-based authorization (user-owned resources)

---

### Rate Limiting & Throttling

**Resource:** [references/rate-limiting-patterns.md](references/rate-limiting-patterns.md)

- Token Bucket algorithm (recommended, allows bursts)
- Fixed Window vs Sliding Window
- Rate limit headers (`X-RateLimit-*`)
- Tiered rate limits (free, paid, enterprise)
- Redis-based distributed rate limiting
- Per-user, per-endpoint, and per-API-key strategies

---

## Navigation: Extended Resources

### API Design & Best Practices

- **[api-design-best-practices.md](references/api-design-best-practices.md)** - Comprehensive API design principles
- **[versioning-strategies.md](references/versioning-strategies.md)** - URL, header, and query parameter versioning
- **[api-security-checklist.md](references/api-security-checklist.md)** - OWASP API Security Top 10

### GraphQL & gRPC

- **[graphql-patterns.md](references/graphql-patterns.md)** - Schema design, resolvers, N+1 queries, DataLoader
- **gRPC patterns** - See [software-backend](../software-backend/SKILL.md) for Protocol Buffers and service definitions

### tRPC (TypeScript-First)

- **[trpc-patterns.md](references/trpc-patterns.md)** - End-to-end type safety, procedures, React Query integration
  - When to use tRPC vs GraphQL vs REST
  - Auth middleware patterns
  - Server-side rendering with Next.js

### OpenAPI & Documentation

- **[openapi-guide.md](references/openapi-guide.md)** - OpenAPI 3.1 specifications, Swagger UI, Redoc
- **Templates:** [assets/openapi-template.yaml](assets/openapi-template.yaml) - Complete OpenAPI spec example

### Webhooks & Event-Driven APIs

- **[webhook-patterns.md](references/webhook-patterns.md)** - Webhook design, delivery guarantees, signature verification, retry policies, DLQs

### Real-Time APIs

- **[real-time-api-patterns.md](references/real-time-api-patterns.md)** - WebSockets, SSE, long polling, gRPC streaming, protocol selection guide

### API Testing

- **[api-testing-patterns.md](references/api-testing-patterns.md)** - Contract testing, integration testing, load testing, chaos testing for APIs

### Optional: AI/Automation (LLM/Agent APIs)

- **[llm-agent-api-contracts.md](references/llm-agent-api-contracts.md)** - Streaming, long-running jobs, safety guardrails, observability

---

## Navigation: Templates

Production-ready, copy-paste API implementations with authentication, database, validation, and docs.

### Framework-Specific Templates

- **FastAPI (Python)**: [assets/fastapi/fastapi-complete-api.md](assets/fastapi/fastapi-complete-api.md)
  - Async/await, Pydantic v2, JWT auth, SQLAlchemy 2.0, pagination, OpenAPI docs

- **Express.js (Node/TypeScript)**: [asset