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