dev-api-design

# 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)**: [assets/express-nodejs/express-complete-api.md](assets/express-nodejs/express-complete-api.md)
  - TypeScript, Zod validation, Prisma ORM, JWT refresh tokens, rate limiting

- **Django REST Framework**: [assets/django-rest/django-rest-complete-api.md](assets/django-rest/django-rest-complete-api.md)
  - ViewSets, serializers, Simple JWT, permissions, DRF filtering/pagination

- **Spring Boot (Java)**: [assets/spring-boot/spring-boot-complete-api.md](assets/spring-boot/spring-boot-complete-api.md)
  - Spring Security JWT, Spring Data JPA, Bean Validation, Springdoc OpenAPI

### Cross-Platform Patterns

- **[api-patterns-universal.md](assets/cross-platform/api-patterns-universal.md)** - Universal patterns for all frameworks
  - Authentication strategies, pagination, caching, versioning, validation
- **[template-api-governance.md](assets/cross-platform/template-api-governance.md)** - API governance, deprecation, multi-tenancy
  - Deprecation policy (90-day timeline), backward compatibility rules, error model templates
- **[template-api-design-review-checklist.md](assets/cross-platform/template-api-design-review-checklist.md)** - Production API review checklist (security, reliability, operability)
- **[template-api-error-model.md](assets/cross-platform/template-api-error-model.md)** - RFC 9457 Problem Details + stable error code registry

---

## Do / Avoid

### GOOD: Do

- Version APIs from day one
- Document deprecation policy before first deprecation
- Treat breaking changes as a major version (and keep minor changes backward compatible)
- Include trace IDs in all error responses
- Return appropriate HTTP status codes
- Implement rate limiting with clear headers
- Use RFC 9457 Problem Details for errors

### BAD: Avoid

- Removing fields without deprecation period
- Changing field types in existing versions
- Using verbs in resource names (nouns only)
- Returning 500 for client errors
- Breaking changes without major version bump
- Mixing tenant data without explicit isolation
- Action endpoints everywhere (/doSomething)

---

## Anti-Patterns

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| **Instant deprecation** | Breaks clients | 90-day minimum sunset period |
| **Action endpoints** | Inconsistent API | Use resources + HTTP verbs |
| **Version in body** | Hard to route, debug | Version in URL or header |
| **Generic errors** | Poor DX | Specific error codes + messages |
| **No rate limit headers** | Clients can't back off | Include X-RateLimit-* |
| **Tenant ID in URL only** | Forgery risk | Validate against auth token |
| **Leaky abstractions** | Tight coupling | Design stable contracts |

---

## Optional: AI/Automation

> **Note**: AI tools assist but contracts need human review.

- **OpenAPI linting** — Spectral, Redocly in CI/CD
- **Breaking change detection** — oasdiff automated checks
- **SDK generation** — From OpenAPI spec on changes
- **Contract testing** — Pact, Dredd automation

### Bounded Claims

- AI-generated OpenAPI specs require human review
- Automated deprecation detection needs manual confirmation
- SDK generation requires type verification

---

## External Resources

See [data/sources.json](data/sources.json) for:

- Official REST, GraphQL, gRPC documentation
- OpenAPI/Swagger tools and validators
- API design style guides (Google, Microsoft, Stripe)
- Security standards (OWASP API Security Top 10)
- Testing tools (Postman, Insomnia, Paw)

---

## Related Skills

This skill works best when combined with other specialized skills:

### Backend Development

- **[software-backend](../software-backend/SKILL.md)** - Production backend patterns (Node.js, Python, Java frameworks)
  - Use when implementing API server infrastructure
  - Covers database integration, middleware, error handling

### Security & Authentication

- **[software-security-appsec](../software-security-appsec/SKILL.md)** - Application security patterns
  - Critical for securing API endpoints
  - Covers OWASP vulnerabilities, authentication flows, input validation

### Database & Data Layer

- **[data-sql-optimization](../data-sql-optimization/SKILL.md)** - SQL optimization and database patterns
  - Essential for API performance (query optimization, indexing)
  - Use when APIs interact with relational databases

### Testing & Quality

- **[qa-testing-strategy](../qa-testing-strategy/SKILL.md)** - Test strategy and automation
  - Contract testing for API specifications
  - Integration testing for API endpoints

### DevOps & Deployment

- **[ops-devops-platform](../ops-devops-platform/SKILL.md)** - Platform engineering and deployment
  - API gateway configuration
  - CI/CD pipelines for API deployments

### Documentation

- **[docs-codebase](../docs-codebase/SKILL.md)** - Technical documentation standards
  - API reference documentation structure
  - Complements OpenAPI auto-generated docs

### Architecture

- **[software-architecture-design](../software-architecture-design/SKILL.md)** - System design patterns
  - Microservices architecture with APIs
  - API gateway patterns, service mesh integration

### Performance & Observability

- **[qa-observability](../qa-observability/SKILL.md)** - Performance optimization and monitoring
  - API latency monitoring, distributed tracing
  - Performance budgets for API endpoints

---

## Usage Notes

**For the agent:**

- Apply RESTful principles by default unless user requests GraphQL/gRPC
- Always include pagination for list endpoints
- Use RFC 9457 format for error responses
- Include authentication in all templates (JWT or API keys)
- Reference framework-specific templates for complete implementations
- Link to relevant resources for deep-dive guidance

**Success Criteria:** APIs are discoverable, consistent, well-documented, secure, and follow HTTP/GraphQL semantics correctly.

---

## Time-Sensitive Recommendations

If a user asks for "best" tools/frameworks, "latest" standards, or whether something is still relevant in 2026, do a quick web search using whatever browsing/search tool is available in the current environment. If web access is unavailable, answer from stable principles, state assumptions (traffic, latency, team skills, ecosystem), and avoid overstating currency.