api-design-principles

Review the current code or API against API design principles — identifies violations and suggests improvements

Use this agent for comprehensive API design audits of endpoints, routes, error handling, or API architecture. Examples: <example>Context: User has built a REST API and wants it reviewed. user: "Review my API against REST best practices" assistant: "I'll use the api-design-reviewer agent to audit the API." <commentary>API review involves routes, HTTP methods, error handling, auth, pagination — the agent audits against all relevant principles.</commentary></example> <example>Context: User finished building API error handling. user: "Check if my error responses follow good API patterns" assistant: "I'll use the api-design-reviewer agent to review the error handling." <commentary>Error handling touches status codes, error envelopes, validation errors — comprehensive audit needed.</commentary></example> <example>Context: User is designing a new API and wants a design check. user: "Does my API design follow best practices?" assistant: "I'll use the api-design-reviewer agent to evaluate the API design." <commentary>New API design involves routes, naming, methods, auth, responses — multi-principle audit.</commentary></example>

This skill should be used when the user is implementing bulk or batch API operations, choosing between REST and GraphQL or gRPC, designing real-time APIs with SSE or WebSockets, implementing multi-tenant API isolation, setting up API gateways, or applying CQRS and event sourcing patterns. Covers batch operations, protocol comparison, real-time patterns, multi-tenancy, and API gateway selection.

This skill should be used when the user is designing API authentication, implementing API keys with prefixes, choosing between API keys and OAuth, setting up JWT tokens, implementing Bearer token authentication, designing API key rotation, or scoping API key permissions. Covers Stripe-style prefixed keys (sk_live_, pk_test_), OAuth 2.0 flows, JWT patterns, and key management.

This skill should be used when the user is implementing HTTP caching, configuring Cache-Control headers, using ETags and conditional requests, setting up CDN caching for APIs, implementing response compression, choosing between gzip and Brotli, configuring HTTP/2, or implementing circuit breakers. Covers Cache-Control directives, ETag validation, CDN strategies, compression, and resilience patterns.

This skill should be used when the user is writing API documentation, designing developer onboarding, building interactive API explorers, generating SDKs, creating code examples, setting up sandbox environments, implementing API changelogs, or optimizing time-to-first-API-call. Covers three-panel docs layout, interactive try-it functionality, multi-language examples, and developer experience optimization.

This skill should be used when the user is designing API error responses, choosing HTTP status codes, implementing error envelopes, handling validation errors, creating per-field error messages, or following RFC 9457 Problem Details. Covers status code selection (2xx-5xx), consistent error formats, Stripe/GitHub/Twilio error patterns, and request/trace ID correlation.

1 hook across 1 event