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
| $ARGUMENTS |
Action |
design <requirements> |
Design a new API from requirements |
spec <code or path> |
Generate OpenAPI 3.1 spec from existing code |
review <spec or path> |
Audit an existing API design |
version <spec or path> |
Versioning and deprecation strategy |
compat <old> <new> |
Backward compatibility diff analysis |
sdk <spec or path> |
Scaffold client code structure |
| Natural language about API design |
Auto-detect mode from intent |
| Empty |
Show mode menu with examples |
Mode Menu (empty args)
| # |
Mode |
Example |
| 1 |
Design |
design "User management API with RBAC" |
| 2 |
Spec |
spec src/routes/ |
| 3 |
Review |
review openapi.yaml |
| 4 |
Version |
version openapi.yaml |
| 5 |
Compat |
compat v1.yaml v2.yaml |
| 6 |
SDK |
sdk openapi.yaml |
Pick a number or describe what you need.
Protocol Detection
Detect the API protocol from input before entering any mode. Classification determines which conventions and patterns apply.
Detection signals:
| Signal |
REST |
GraphQL |
gRPC |
| File extension |
.yaml, .json (OpenAPI) |
.graphql, .gql |
.proto |
| Keywords |
endpoint, resource, CRUD, path |
query, mutation, subscription, resolver |
service, rpc, message, protobuf |
| URL patterns |
/api/v1/resources |
/graphql |
gRPC service names |
| Code patterns |
Express/FastAPI routes, controllers |
Schema definitions, resolvers |
Proto service definitions |
Routing:
- Clear signal for one protocol: proceed with that protocol's conventions
- Mixed signals or ambiguous: ask user — "Which protocol? [REST / GraphQL / gRPC]"
- No protocol context (pure requirements): default to REST, note assumption
Load references/rest-conventions.md, references/graphql-patterns.md, or references/grpc-patterns.md based on detected protocol.
Mode A: Design
New API from requirements. Read references/rest-conventions.md (or protocol-specific reference).
Design Steps
- Parse requirements — Extract resources, relationships, operations, auth needs, constraints
- Resource modeling — Define resources with attributes, relationships, cardinality
- Endpoint design — Map CRUD + custom operations to endpoints following protocol conventions
- Request/response schemas — Define payloads with types, validation rules, examples
- Auth strategy — Recommend auth approach (API key, OAuth2, JWT) based on use case
- Error contract — Define error response format with codes, messages, detail objects
- Pagination & filtering — Apply cursor or offset pagination, filter query patterns
- Rate limiting — Recommend limits based on endpoint sensitivity and expected load
- Generate spec — Output complete OpenAPI 3.1 YAML
- Validate — Run
scripts/api-spec-validator.py on generated spec
Mode B: Spec
Generate OpenAPI 3.1 from existing code.
Spec Steps
- Scan codebase — Read route definitions, controllers, handlers, decorators
- Extract endpoints — Map code to path + method + parameters + response types
- Infer schemas — Build request/response schemas from type annotations or runtime types
- Generate spec — Output OpenAPI 3.1 YAML with all discovered endpoints
- Validate — Run
scripts/api-spec-validator.py
- Gap report — List endpoints missing descriptions, examples, or error responses
Mode C: Review
Audit existing API design. Read-only analysis.
Review Steps
- Parse spec — Load and validate the OpenAPI document
- Run validator —
scripts/api-spec-validator.py for structural issues
- Run endpoint matrix —
scripts/api-endpoint-matrix.py for surface overview
- Convention check — Verify naming, HTTP method usage, status codes against
references/rest-conventions.md
- Security audit — Check auth coverage, HTTPS enforcement, sensitive data exposure
- Consistency check — Verify naming patterns, response envelope consistency, error format uniformity
- Report — Present findings by severity (critical, warning, info) with specific fix recommendations
Mode D: Version
Versioning and deprecation strategy.
Version Steps
- Analyze current state — Parse spec, identify version indicators
- Recommend strategy — Compare URL path vs header vs query param versioning (load
references/versioning-strategies.md)
- Deprecation plan — Timeline, sunset headers, migration guides for deprecated endpoints
- Version matrix — Table showing which endpoints exist in which versions
- Migration guide template — Skeleton for consumer migration documentation
Mode E: Compat
Backward compatibility diff between two spec versions.
Compat Steps
- Load both specs — Parse old and new OpenAPI documents
- Run compat checker —
scripts/compat-checker.py <old> <new>
- Classify changes — Breaking vs non-breaking with change type and location
- Impact assessment — Which consumers are affected, estimated migration effort
- Remediation — For each breaking change, suggest backward-compatible alternatives
Mode F: SDK
Scaffold client code structure from a spec. NOT a publishable SDK package — a structural starting point.
SDK Steps
- Parse spec — Extract endpoints, schemas, auth requirements
- Group by resource — Organize endpoints into logical client modules
- Generate client skeleton — Method stubs with typed parameters and return types
- Auth integration — Wire auth mechanism into client constructor
- Error handling — Map API error codes to client exceptions
- Usage examples — One example per resource showing common operations
Scripts
| Script |
Purpose |
Run When |
scripts/api-spec-validator.py |
Validate OpenAPI 3.x for completeness and best practices |
Design, Spec, Review |
scripts/api-endpoint-matrix.py |
Extract endpoint inventory from spec |
Review, Version, SDK |
scripts/compat-checker.py |
Compare two specs for breaking changes |
Compat |
Script Invocation
uv run python skills/api-designer/scripts/api-spec-validator.py <spec-path>
uv run python skills/api-designer/scripts/api-endpoint-matrix.py <spec-path>
uv run python skills/api-designer/scripts/compat-checker.py <old-spec> <new-spec>
All scripts output JSON to stdout, warnings to stderr.
Reference File Index
| File |
Content |
Read When |
references/rest-conventions.md |
REST best practices, HTTP methods, status codes, naming, pagination, rate limiting |
Design, Spec, Review (REST) |
references/graphql-patterns.md |
GraphQL schema design, query patterns, error handling, subscriptions |
Design, Spec, Review (GraphQL) |
references/grpc-patterns.md |
gRPC service patterns, proto design, streaming, error codes |
Design, Spec, Review (gRPC) |
references/versioning-strategies.md |
URL vs header vs query versioning, deprecation, backward compat checklist |
Version, Compat |
data/http-conventions.json |
HTTP method semantics reference data |
Scripts |
data/status-codes.json |
HTTP status code guide reference data |
Scripts |
Do not load all references at once. Load only what the detected protocol and active mode require.
Critical Rules
- Always detect protocol before entering any mode — never assume REST without evidence
- If protocol is ambiguous, ask the user — do not guess
- Generated specs must pass
api-spec-validator.py before presenting to user
- Every endpoint must have at least one error response defined (4xx or 5xx)
- Never design APIs without pagination for list endpoints returning collections
- Breaking changes in compat mode must include remediation suggestions
- SDK mode produces structural scaffolds only — never claim the output is production-ready
- Use the canonical vocabulary consistently — "spec" not "swagger", "endpoint" not "route"
- All specs target OpenAPI 3.1 — do not generate Swagger 2.0 or OpenAPI 3.0
- NOT for MCP servers (use mcp-creator) or frontend API client code
Scope Boundaries
IS for:
- Designing new REST, GraphQL, or gRPC APIs from requirements
- Generating OpenAPI specs from existing code
- Reviewing and auditing API designs
- Versioning strategy and deprecation planning
- Breaking change analysis between spec versions
- Scaffolding client code structure
NOT for:
- MCP server APIs (use
/mcp-creator)
- Frontend API client implementations
- API gateway configuration
- Runtime API testing or load testing
- Database schema design (use
/database-architect)
1---2name: api-designer3description: Contract-first API design for REST, GraphQL, gRPC. Design, spec, review, version, compat, sdk. Use for API architecture and OpenAPI specs. NOT for MCP servers (mcp-creator) or frontend API calls.4license: MIT5---67# API Designer89Contract-first API design across REST, GraphQL, and gRPC. Produces OpenAPI 3.1 specs, reviews existing APIs, analyzes backward compatibility, and scaffolds client code.1011## Canonical Vocabulary1213| Term | Definition |14|------|-----------|15| **spec** | An OpenAPI 3.1 document (YAML or JSON) describing an API's surface |16| **endpoint** | A path + method combination in a REST API; a query/mutation in GraphQL; an RPC in gRPC |17| **breaking change** | Any modification that causes existing clients to fail without code changes |18| **non-breaking change** | A backward-compatible modification (additive fields, new endpoints, optional params) |19| **resource** | A domain entity exposed through the API (noun-based URL segment in REST) |20| **contract** | The formal agreement between API producer and consumer defined by the spec |21| **protocol** | The API paradigm: REST, GraphQL, or gRPC |22| **surface** | The complete set of endpoints, types, and operations an API exposes |23| **versioning strategy** | How breaking changes are communicated: URL path, header, or query parameter |2425## Dispatch2627| $ARGUMENTS | Action |28|------------|--------|29| `design <requirements>` | Design a new API from requirements |30| `spec <code or path>` | Generate OpenAPI 3.1 spec from existing code |31| `review <spec or path>` | Audit an existing API design |32| `version <spec or path>` | Versioning and deprecation strategy |33| `compat <old> <new>` | Backward compatibility diff analysis |34| `sdk <spec or path>` | Scaffold client code structure |35| Natural language about API design | Auto-detect mode from intent |36| Empty | Show mode menu with examples |3738### Mode Menu (empty args)3940| # | Mode | Example |41|---|------|---------|42| 1 | Design | `design "User management API with RBAC"` |43| 2 | Spec | `spec src/routes/` |44| 3 | Review | `review openapi.yaml` |45| 4 | Version | `version openapi.yaml` |46| 5 | Compat | `compat v1.yaml v2.yaml` |47| 6 | SDK | `sdk openapi.yaml` |4849> Pick a number or describe what you need.5051## Protocol Detection5253Detect the API protocol from input before entering any mode. Classification determines which conventions and patterns apply.5455**Detection signals:**5657| Signal | REST | GraphQL | gRPC |58|--------|------|---------|------|59| File extension | `.yaml`, `.json` (OpenAPI) | `.graphql`, `.gql` | `.proto` |60| Keywords | endpoint, resource, CRUD, path | query, mutation, subscription, resolver | service, rpc, message, protobuf |61| URL patterns | `/api/v1/resources` | `/graphql` | gRPC service names |62| Code patterns | Express/FastAPI routes, controllers | Schema definitions, resolvers | Proto service definitions |6364**Routing:**65- Clear signal for one protocol: proceed with that protocol's conventions66- Mixed signals or ambiguous: ask user — "Which protocol? [REST / GraphQL / gRPC]"67- No protocol context (pure requirements): default to REST, note assumption6869Load `references/rest-conventions.md`, `references/graphql-patterns.md`, or `references/grpc-patterns.md` based on detected protocol.7071## Mode A: Design7273New API from requirements. Read `references/rest-conventions.md` (or protocol-specific reference).7475### Design Steps76771. **Parse requirements** — Extract resources, relationships, operations, auth needs, constraints782. **Resource modeling** — Define resources with attributes, relationships, cardinality793. **Endpoint design** — Map CRUD + custom operations to endpoints following protocol conventions804. **Request/response schemas** — Define payloads with types, validation rules, examples815. **Auth strategy** — Recommend auth approach (API key, OAuth2, JWT) based on use case826. **Error contract** — Define error response format with codes, messages, detail objects837. **Pagination & filtering** — Apply cursor or offset pagination, filter query patterns848. **Rate limiting** — Recommend limits based on endpoint sensitivity and expected load859. **Generate spec** — Output complete OpenAPI 3.1 YAML8610. **Validate** — Run `scripts/api-spec-validator.py` on generated spec8788## Mode B: Spec8990Generate OpenAPI 3.1 from existing code.9192### Spec Steps93941. **Scan codebase** — Read route definitions, controllers, handlers, decorators952. **Extract endpoints** — Map code to path + method + parameters + response types963. **Infer schemas** — Build request/response schemas from type annotations or runtime types974. **Generate spec** — Output OpenAPI 3.1 YAML with all discovered endpoints985. **Validate** — Run `scripts/api-spec-validator.py`996. **Gap report** — List endpoints missing descriptions, examples, or error responses100101## Mode C: Review102103Audit existing API design. Read-only analysis.104105### Review Steps1061071. **Parse spec** — Load and validate the OpenAPI document1082. **Run validator** — `scripts/api-spec-validator.py` for structural issues1093. **Run endpoint matrix** — `scripts/api-endpoint-matrix.py` for surface overview1104. **Convention check** — Verify naming, HTTP method usage, status codes against `references/rest-conventions.md`1115. **Security audit** — Check auth coverage, HTTPS enforcement, sensitive data exposure1126. **Consistency check** — Verify naming patterns, response envelope consistency, error format uniformity1137. **Report** — Present findings by severity (critical, warning, info) with specific fix recommendations114115## Mode D: Version116117Versioning and deprecation strategy.118119### Version Steps1201211. **Analyze current state** — Parse spec, identify version indicators1222. **Recommend strategy** — Compare URL path vs header vs query param versioning (load `references/versioning-strategies.md`)1233. **Deprecation plan** — Timeline, sunset headers, migration guides for deprecated endpoints1244. **Version matrix** — Table showing which endpoints exist in which versions1255. **Migration guide template** — Skeleton for consumer migration documentation126127## Mode E: Compat128129Backward compatibility diff between two spec versions.130131### Compat Steps1321331. **Load both specs** — Parse old and new OpenAPI documents1342. **Run compat checker** — `scripts/compat-checker.py <old> <new>`1353. **Classify changes** — Breaking vs non-breaking with change type and location1364. **Impact assessment** — Which consumers are affected, estimated migration effort1375. **Remediation** — For each breaking change, suggest backward-compatible alternatives138139## Mode F: SDK140141Scaffold client code structure from a spec. NOT a publishable SDK package — a structural starting point.142143### SDK Steps1441451. **Parse spec** — Extract endpoints, schemas, auth requirements1462. **Group by resource** — Organize endpoints into logical client modules1473. **Generate client skeleton** — Method stubs with typed parameters and return types1484. **Auth integration** — Wire auth mechanism into client constructor1495. **Error handling** — Map API error codes to client exceptions1506. **Usage examples** — One example per resource showing common operations151152## Scripts153154| Script | Purpose | Run When |155|--------|---------|----------|156| `scripts/api-spec-validator.py` | Validate OpenAPI 3.x for completeness and best practices | Design, Spec, Review |157| `scripts/api-endpoint-matrix.py` | Extract endpoint inventory from spec | Review, Version, SDK |158| `scripts/compat-checker.py` | Compare two specs for breaking changes | Compat |159160### Script Invocation161162```bash163uv run python skills/api-designer/scripts/api-spec-validator.py <spec-path>164uv run python skills/api-designer/scripts/api-endpoint-matrix.py <spec-path>165uv run python skills/api-designer/scripts/compat-checker.py <old-spec> <new-spec>166```167168All scripts output JSON to stdout, warnings to stderr.169170## Reference File Index171172| File | Content | Read When |173|------|---------|-----------|174| `references/rest-conventions.md` | REST best practices, HTTP methods, status codes, naming, pagination, rate limiting | Design, Spec, Review (REST) |175| `references/graphql-patterns.md` | GraphQL schema design, query patterns, error handling, subscriptions | Design, Spec, Review (GraphQL) |176| `references/grpc-patterns.md` | gRPC service patterns, proto design, streaming, error codes | Design, Spec, Review (gRPC) |177| `references/versioning-strategies.md` | URL vs header vs query versioning, deprecation, backward compat checklist | Version, Compat |178| `data/http-conventions.json` | HTTP method semantics reference data | Scripts |179| `data/status-codes.json` | HTTP status code guide reference data | Scripts |180181Do not load all references at once. Load only what the detected protocol and active mode require.182183## Critical Rules1841851. Always detect protocol before entering any mode — never assume REST without evidence1862. If protocol is ambiguous, ask the user — do not guess1873. Generated specs must pass `api-spec-validator.py` before presenting to user1884. Every endpoint must have at least one error response defined (4xx or 5xx)1895. Never design APIs without pagination for list endpoints returning collections1906. Breaking changes in compat mode must include remediation suggestions1917. SDK mode produces structural scaffolds only — never claim the output is production-ready1928. Use the canonical vocabulary consistently — "spec" not "swagger", "endpoint" not "route"1939. All specs target OpenAPI 3.1 — do not generate Swagger 2.0 or OpenAPI 3.019410. NOT for MCP servers (use mcp-creator) or frontend API client code195196## Scope Boundaries197198**IS for:**199- Designing new REST, GraphQL, or gRPC APIs from requirements200- Generating OpenAPI specs from existing code201- Reviewing and auditing API designs202- Versioning strategy and deprecation planning203- Breaking change analysis between spec versions204- Scaffolding client code structure205206**NOT for:**207- MCP server APIs (use `/mcp-creator`)208- Frontend API client implementations209- API gateway configuration210- Runtime API testing or load testing211- Database schema design (use `/database-architect`)
wyattowalsh