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.

This skill should be used when the user is choosing HTTP methods for API endpoints, designing CRUD operations, implementing idempotent operations, deciding between PUT and PATCH, handling bulk operations, or working with HTTP verb semantics. Covers GET, POST, PUT, PATCH, DELETE with idempotency rules, status code pairings, and real-world patterns.

This skill should be used when the user is designing ID formats for API resources, implementing type-safe identifiers, choosing between UUID and prefixed IDs, generating IDs with KSUID or ULID, creating ID validation, or following Stripe's prefixed ID pattern. Covers prefix conventions, ID generation, validation, and debugging benefits.

This skill should be used when the user is implementing rate limiting, choosing rate limit algorithms, adding rate limit headers, securing API endpoints, preventing OWASP API Top 10 vulnerabilities, configuring CORS, validating input, or implementing request signing. Covers sliding window, token bucket, and leaky bucket algorithms, rate limit response headers, and API security best practices.

This skill should be used when the user is designing API response formats, implementing pagination (cursor, offset, keyset), creating list endpoints, designing response envelopes, implementing expandable/embeddable objects, or structuring API output. Covers Stripe-style cursor pagination, consistent list envelopes, expand patterns, and response metadata.

This skill should be used when the user is designing API routes, URL structures, endpoint naming, resource naming conventions, query parameters vs path parameters, JSON field naming (snake_case vs camelCase), nesting depth, or API URL patterns. Covers plural nouns, flat vs hierarchical URLs, field naming conventions, and real-world patterns from Stripe, GitHub, Twilio, and Google.

This skill should be used when the user asks "which API design skill should I use", "show me all API principles", "help me pick an API pattern", or at the start of any RESTful API design conversation. Provides the index of all twelve principle skills and ensures the right ones are invoked before any API design work begins.

This skill should be used when the user is designing API versioning strategy, choosing between URL path and header-based versioning, implementing Stripe-style date-based versioning, planning API deprecation, using sunset headers, or evolving an API without breaking clients. Covers URL versioning, additive evolution, backward compatibility, and deprecation communication.

This skill should be used when the user is designing webhook systems, implementing webhook signing with HMAC-SHA256, building webhook retry logic, choosing event naming conventions, handling webhook ordering, implementing webhook endpoints, or building event-driven API integrations. Covers Stripe-style webhook patterns, signature verification, exponential backoff retries, and event deduplication.

1 hook across 1 event