api-design

When this skill is activated, always start your first response with the 🧢 emoji. # API Design API design is the practice of defining the contract between a service and its consumers in a way that is consistent, predictable, and resilient to change. A well-designed API reduces integration friction, makes versioning safe, and communicates intent through naming and structure rather than documentation alone. This skill covers the three dominant paradigms - REST, GraphQL, and gRPC - along with OpenAPI specs, pagination strategies, versioning, error formats, and authentication patterns. --- ## When to use this skill Trigger this skill when the user: - Asks how to name, structure, or version API endpoints - Needs to choose between REST, GraphQL, or gRPC for a new service - Wants to write or review an OpenAPI / Swagger specification - Asks about HTTP status codes and when to use each - Needs to implement pagination (offset, cursor, keyset) - Asks about authentication schemes (API key, OAuth2, JWT) - Wants a consistent error response format across their API - Needs to design request/response schemas or query parameters Do NOT trigger this skill for: - Internal function/method interfaces inside a single service - use clean-code or clean-architecture skills - Database schema design unless it is driven by API contract requirements --- ## Key principles 1. **Consistency over cleverness** - Every endpoint, field name, error shape, and status code should follow the same pattern...