rest-api-designlisted

Expert guide for designing and reviewing REST APIs. Use this skill whenever the user: is adding, designing, or renaming an HTTP endpoint or resource; asks what HTTP method or status code to use; is shaping a request or response payload, an error format, or a validation-error response; is adding pagination, filtering, sorting, or bulk operations to a collection endpoint; is versioning an API, planning a breaking change, or deprecating a field/endpoint; is adding authentication, authorization, rate limiting, or reviewing an endpoint for security issues (IDOR, mass assignment, enumeration); is writing, editing, or linting an OpenAPI/Swagger spec; or is reviewing/auditing an existing API for RESTful consistency. Also use when the user says things like "design the API for X", "is this endpoint RESTful?", "what status code should I return here", or "review my API" — even if they don't say "REST" explicitly.
eagerworks/skills · ★ 1 · API & Backend · score 67

Install: claude install-skill eagerworks/skills

# REST API Design Skill This skill teaches resource modeling, HTTP semantics, payload/error shapes, pagination, versioning, auth, and OpenAPI — framework-agnostic (plain HTTP, JSON, and OpenAPI YAML). It states one opinionated house style with explicit escape hatches, but that style is a *fallback*, not a mandate: **an existing API's conventions always win.** ## Survey the Existing API First — Do This Before Designing Before proposing a single path or field name, check whether an API already exists in the repo. Never design a new endpoint in isolation from the ones that already ship. ```bash # Find the API surface find . -iname "openapi*.yml" -o -iname "openapi*.yaml" -o -iname "swagger*.json" -not -path "*/node_modules/*" grep -rlE "router\.|@(Get|Post|Put|Patch|Delete)Mapping|app\.(get|post|put|patch|delete)\(|resources :" \ --include="*.rb" --include="*.ts" --include="*.js" --include="*.py" --include="*.java" --include="*.go" . ``` Read a handful of existing endpoints (routes/controllers, serializers, and their tests) and fill in what you observe: | Convention | What to check | |---|---| | Path casing & pluralization | `/user-accounts` vs `/userAccounts` vs `/users` | | JSON key casing | `camelCase` vs `snake_case` vs `kebab-case` | | ID format | UUID/ULID vs sequential integer, in path and in body | | Pagination style | cursor (`?cursor=`), offset (`?page=`), or none | | Error envelope | RFC 9457 `problem+json`, a custom `{error: {...}}` shape, or bare messages |