API Designer

Overview

The API Designer skill produces consistent, developer-friendly REST API designs following industry conventions: RESTful resource naming, correct HTTP method semantics, standardized status codes, structured error responses, pagination patterns, and versioning strategies. It includes OpenAPI 3.0 spec snippets so designs can be immediately documented and validated. A well-designed API is intuitive to consume, easy to evolve, and resilient to misuse.

When to Use

• Designing a new API surface for a service or microservice
• Adding endpoints to an existing API and needing consistency
• Reviewing an API design for RESTful correctness
• Writing an OpenAPI/Swagger specification
• Deciding on versioning, pagination, or error response format

When NOT to Use

• Implementing the actual server-side logic (use a framework guide instead)
• Designing a GraphQL schema (different paradigm)
• Designing a WebSocket or streaming protocol API
• Internal function/library API design (different conventions apply)