rest-api-designlisted

# 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 |