dev-api-design

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

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

---

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)
    │
    ├─ 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)
    │
    └─ Streaming or bidirectional?
        └─ **gRPC** (HTTP/2 streaming) or **WebSockets**

---

Navigation: Core API Patterns

RESTful API Design

Resource: resources/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: resources/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: resources/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: resources/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: resources/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

OpenAPI & Documentation

• openapi-guide.md - OpenAPI 3.1 specifications, Swagger UI, Redoc
• Templates: templates/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): templates/fastapi/fastapi-complete-api.md

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

• Express.js (Node/TypeScript): templates/express-nodejs/express-complete-api.md

  • TypeScript, Zod validation, Prisma ORM, JWT refresh tokens, rate limiting

• Django REST Framework: templates/django-rest/django-rest-complete-api.md

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

• Spring Boot (Java): templates/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

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)

---

Quick Decision Matrix

Scenario	Recommendation
Public API for third parties	REST with OpenAPI docs
Internal microservices	gRPC for performance, REST for simplicity
Client needs flexible queries	GraphQL
Real-time updates	GraphQL Subscriptions or WebSockets
Simple CRUD operations	REST
Complex data fetching	GraphQL
High throughput required	gRPC
Mobile/web clients	REST or GraphQL

---

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.