Design Robust and Scalable APIs

This skill is a decision-making index for API design: rather than fixed patterns to copy, it maps ten reference files (REST vs GraphQL vs tRPC decision tree, REST resource/method/status-code conventions, response envelope/error/pagination format, GraphQL schema design, tRPC for TypeScript monorepos, versioning strategies, auth pattern selection, rate limiting, OpenAPI/Swagger documentation, and OWASP API security testing) to read selectively based on the specific API decision at hand.

Use it when choosing an API style, designing REST endpoints, defining a response format, planning API versioning or auth, setting up rate limiting, or documenting an API. The skill's own rule is to read only the reference file relevant to the current request, not all of them - it explicitly frames itself as teaching how to think through API decisions for the current context rather than copying a fixed, one-size-fits-all pattern.

A seven-item decision checklist before designing an API: has the user been asked about API consumers, has an API style (REST/GraphQL/tRPC) been chosen for this specific context, is there a consistent response format defined, is a versioning strategy planned, have authentication needs been considered, is rate limiting planned, and is a documentation approach defined. Related skills for adjacent concerns: @[skills/backend-development] for implementation, @[skills/database-design] for data structure, and @[skills/security-hardening] for security details.

Named anti-patterns to avoid: defaulting to REST for everything, using verbs in REST endpoints (e.g. /getUsers), returning inconsistent response formats, exposing internal errors to clients, and skipping rate limiting - instead, choose the API style based on context, ask about client requirements, document thoroughly, and use appropriate status codes. A bundled script, scripts/api_validator.py, validates API endpoints and is run as python scripts/api_validator.py <project_path>, pointed at the project directory being reviewed.

Developers and architects deciding how to design or evolve an API - style, response format, versioning, auth, rate limiting, documentation - who want a structured decision checklist and anti-pattern list rather than defaulting to one pattern out of habit. Each reference file is scoped to one decision - for example rest.md covers resource naming, HTTP methods, and status codes, while auth.md covers choosing among JWT, OAuth, Passkey, and API Keys - so only the file matching the immediate question needs to be read - response.md for the envelope/error/pagination format, graphql.md for schema design and when GraphQL is actually warranted, and trpc.md for TypeScript-monorepo type safety.