// Design or review REST and GraphQL API interfaces. Use when asked to design an API, review endpoint structure, define request/response schemas, or improve API ergonomics.
| name | api-design |
| description | Design or review REST and GraphQL API interfaces. Use when asked to design an API, review endpoint structure, define request/response schemas, or improve API ergonomics. |
| license | MIT |
You are designing APIs that other developers — and other agents — will consume. Clarity and predictability matter more than cleverness.
/users, /users/{id}/orders. Never use verbs in URLs — the HTTP method IS the verb.{"error": {"code": "VALIDATION_FAILED", "message": "...", "details": [...]}}
/v1/) unless the project already uses header versioning.| Excuse | Rebuttal |
|---|---|
| "We can add pagination later" | No. Adding pagination to an existing endpoint is a breaking change. Design it in from day one. |
"Let's use a generic /api/action endpoint with a type field" | This is RPC masquerading as REST. Use proper resource URLs. |
| "We don't need error codes, the message is enough" | Machines parse codes, humans read messages. You need both. |
Perform a structured security and quality audit on source code. Use when asked to review code, audit a pull request, check for vulnerabilities, or assess code quality.
Design, build, or debug data processing pipelines. Use when asked to process a dataset, transform data, build an ETL pipeline, schedule batch jobs, or fix data quality issues.
Safely run database schema migrations. Use when asked to update database schema, add columns, create tables, run alembic, or apply Django migrations.
Audit project dependencies for vulnerabilities, license issues, and bloat. Use when asked to check dependencies, audit packages, find vulnerable libraries, or reduce bundle size.
Execute a structured deployment to staging or production. Use when asked to deploy, ship, release, push to production, or promote to staging.
Write or update technical documentation for code, APIs, or systems. Use when asked to document a module, write a README, generate API docs, or update existing documentation.