dev-api-design

name	dev-api-design
description	Production-grade API design patterns for REST, GraphQL, gRPC, and tRPC. Covers API architecture, OpenAPI/Swagger specs, versioning/deprecation, authentication/authorization, rate limiting, pagination, error models, contract testing, and developer documentation.

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

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

• 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

• 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

• 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

• 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

• 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 - Comprehensive API design principles
• versioning-strategies.md - URL, header, and query parameter versioning
• api-security-checklist.md - OWASP API Security Top 10

GraphQL & gRPC

• graphql-patterns.md - Schema design, resolvers, N+1 queries, DataLoader
• gRPC patterns - See software-backend for Protocol Buffers and service definitions

tRPC (TypeScript-First)

• 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 - OpenAPI 3.1 specifications, Swagger UI, Redoc
• Templates: assets/openapi-template.yaml - Complete OpenAPI spec example

Webhooks & Event-Driven APIs

• webhook-patterns.md - Webhook design, delivery guarantees, signature verification, retry policies, DLQs

Real-Time APIs

• real-time-api-patterns.md - WebSockets, SSE, long polling, gRPC streaming, protocol selection guide

API Testing

• 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 - 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

  • Async/await, Pydantic v2, JWT auth, SQLAlchemy 2.0, pagination, OpenAPI docs

• Express.js (Node/TypeScript): 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

  • ViewSets, serializers, Simple JWT, permissions, DRF filtering/pagination

• Spring Boot (Java): 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 - Universal patterns for all frameworks
  • Authentication strategies, pagination, caching, versioning, validation
• 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 - Production API review checklist (security, reliability, operability)
• 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 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 - 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 - Application security patterns
  • Critical for securing API endpoints
  • Covers OWASP vulnerabilities, authentication flows, input validation

Database & Data Layer

• data-sql-optimization - SQL optimization and database patterns
  • Essential for API performance (query optimization, indexing)
  • Use when APIs interact with relational databases

Testing & Quality

• qa-testing-strategy - Test strategy and automation
  • Contract testing for API specifications
  • Integration testing for API endpoints

DevOps & Deployment

• ops-devops-platform - Platform engineering and deployment
  • API gateway configuration
  • CI/CD pipelines for API deployments

Documentation

• docs-codebase - Technical documentation standards
  • API reference documentation structure
  • Complements OpenAPI auto-generated docs

Architecture

• software-architecture-design - System design patterns
  • Microservices architecture with APIs
  • API gateway patterns, service mesh integration

Performance & Observability

• qa-observability - 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.