From API Design Expert
Expert API design for REST & GraphQL: resource modeling, status codes, versioning, pagination, idempotency, errors, and contracts. Trigger keywords: API design, REST, RESTful, GraphQL, OpenAPI, endpoint, status code, versioning, pagination, cursor, idempotency, rate limit, contract, schema. Use to design or review HTTP/GraphQL APIs and their contracts.
How this skill is triggered — by the user, by Claude, or both
Slash command
/api-design-expert:api-design-expertThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Design for the consumer and for change. Consistency beats cleverness: predictable naming, one error shape, accurate status codes, additive evolution. The contract is the product.
Design for the consumer and for change. Consistency beats cleverness: predictable naming, one error shape, accurate status codes, additive evolution. The contract is the product.
nodejs-backend-expert / language skill.sql-expert.software-architect.GET /orders/{id}/items. No verbs in paths (/getOrder ❌).200/201/204; 400 (malformed) vs 422 (valid syntax, semantic error) vs 409 (conflict); 401 (unauthenticated) vs 403 (unauthorized); 404; 429 (rate limit). Never 200 with an error body.{ "error": { "code", "message", "details" } } with a stable machine-readable code./v1, or media-type/header). Change additively; never repurpose, retype, or silently drop a field. Deprecate with headers + sunset dates.Idempotency-Key for POST so retries don't double-charge. Document side effects.200 for errors / inventing custom status semantics → use HTTP codes correctly.Consistent error + cursor pagination (REST)
// GET /v1/orders?limit=20&cursor=eyJpZCI6MTQ0fQ
{
"data": [ { "id": "ord_124", "total": 4200, "currency": "USD" } ],
"page": { "next_cursor": "eyJpZCI6MTY0fQ", "has_more": true }
}
// Error (same shape on every endpoint)
{ "error": { "code": "validation_error", "message": "email is invalid",
"details": [ { "field": "email", "rule": "format" } ] } }
Idempotent create
POST /v1/payments
Idempotency-Key: 5f3c… # server returns the same result for retries with this key
nodejs-backend-expert — implementing endpoints and validation.sql-expert — backing pagination/filters efficiently (keyset).security-expert — auth, scopes, rate limiting.rag-expert — designing retrieval/LLM endpoints and streaming responses.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub miaoge-ge/coding-agent-skills --plugin api-design-expert