---

name: dev-api-design description: Production-grade API design patterns for REST, GraphQL, and gRPC. Covers API architecture, OpenAPI/Swagger specs, versioning strategies, authentication flows, rate limiting, pagination, error handling, and documentation best practices for modern API development.

API Development & Design — Quick Reference

This skill provides execution-ready patterns for designing, implementing, and documenting production-grade APIs. Claude should apply these patterns when users need REST API design, GraphQL schemas, OpenAPI specifications, API versioning, authentication flows, or API documentation.

Modern Best Practices (Dec 2025): HTTP semantics and cacheability (RFC 9110), Problem Details error model (RFC 9457), OpenAPI 3.1, API-first + contract testing, strong AuthN/Z boundaries, explicit versioning/deprecation, and operable-by-default APIs (rate limits, idempotency, observability).

---

When to Use This Skill

Claude should invoke this skill when a user requests:

• REST API design and endpoint structure
• GraphQL schema design and resolver patterns
• gRPC service definitions and protocol buffers
• OpenAPI/Swagger specification creation
• API versioning strategies (URL, header, content negotiation)
• Authentication and authorization flows (JWT, OAuth2, API keys)
• Rate limiting, throttling, and quota management
• API pagination, filtering, and sorting patterns
• Error response standardization
• API documentation and developer portals
• API security best practices (OWASP API Security Top 10)
• API testing strategies (contract testing, mock servers)
• API gateway configuration and management

---

Quick Reference

---

Decision Tree: Choosing API Style

CopyUser 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

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 - NEW 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
• Use semantic versioning for API versions
• 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)

---

Quick Decision Matrix

---

Anti-Patterns to Avoid

• Verbs in URLs: /getUserById → /users/:id
• Ignoring HTTP methods: Using GET for mutations
• No versioning: Breaking changes without version bump
• Inconsistent error format: Different error structures per endpoint
• Missing pagination: Returning unbounded lists
• No rate limiting: Allowing unlimited requests
• Poor documentation: Missing examples, outdated specs
• Security by obscurity: Not using HTTPS, weak auth

---

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 Claude:

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

---

Trend Awareness Protocol

IMPORTANT: When users ask recommendation questions about API design, frameworks, or documentation, you MUST use WebSearch to check current trends before answering.

Trigger Conditions

• "What's the best API framework for [language/use case]?"
• "What should I use for [REST/GraphQL/gRPC]?"
• "What's the latest in API design?"
• "Current best practices for [OpenAPI/API versioning]?"
• "Is [approach/tool] still relevant in 2026?"
• "[REST] vs [GraphQL] vs [gRPC]?"
• "Best API documentation tool?"

Required Searches

1. Search: "API design best practices 2026"
2. Search: "[specific framework] vs alternatives 2026"
3. Search: "API trends January 2026"
4. Search: "[REST/GraphQL/gRPC] comparison 2026"

What to Report

After searching, provide:

• Current landscape: What API patterns/tools are popular NOW
• Emerging trends: New frameworks, patterns, or standards gaining traction
• Deprecated/declining: Approaches or tools losing relevance
• Recommendation: Based on fresh data, not just static knowledge

Example Topics (verify with fresh search)

• API frameworks (FastAPI, Express, Spring Boot, tRPC)
• API specification (OpenAPI 3.1, AsyncAPI)
• GraphQL ecosystem (Apollo, Relay, urql)
• API documentation (Swagger UI, Redoc, Stoplight)
• API gateways and management
• API security standards and OWASP
• Contract testing tools (Pact, Specmatic)