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

• 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

Webhooks & Event-Driven APIs

• webhook-patterns.md - Webhook design, delivery guarantees, signature verification, retry policies, DLQs

Real-Time APIs

• real-time-api-patterns.md - WebSockets, SSE, long polling, gRPC streaming, protocol selection guide

API Testing

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

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.