| 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
GraphQL & gRPC
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
Webhooks & Event-Driven APIs
- webhook-patterns.md - Webhook design, delivery guarantees, signature verification, retry policies, DLQs
Real-Time APIs
API Testing
Optional: AI/Automation (LLM/Agent APIs)
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
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.
