version: "1.0.1" name: dev-api-design description: REST/GraphQL/gRPC/tRPC API design patterns. Use when designing APIs, writing OpenAPI specs, versioning, auth, or rate limiting.

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

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

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](../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.

Fact-Checking

• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
• Prefer primary sources; report source links and dates for volatile information.
• If web access is unavailable, state the limitation and mark guidance as unverified.