api-designer
Installation
SKILL.md
API Designer
Contract-first API design across REST, GraphQL, and gRPC. Produces OpenAPI 3.1 specs, reviews existing APIs, analyzes backward compatibility, and scaffolds client code.
Canonical Vocabulary
| Term | Definition |
|---|---|
| spec | An OpenAPI 3.1 document (YAML or JSON) describing an API's surface |
| endpoint | A path + method combination in a REST API; a query/mutation in GraphQL; an RPC in gRPC |
| breaking change | Any modification that causes existing clients to fail without code changes |
| non-breaking change | A backward-compatible modification (additive fields, new endpoints, optional params) |
| resource | A domain entity exposed through the API (noun-based URL segment in REST) |
| contract | The formal agreement between API producer and consumer defined by the spec |
| protocol | The API paradigm: REST, GraphQL, or gRPC |
| surface | The complete set of endpoints, types, and operations an API exposes |
| versioning strategy | How breaking changes are communicated: URL path, header, or query parameter |
Dispatch
Related skills