SkillScan: pass
API design review with scoring rubric
REST and GraphQL contract review checklist (naming, errors, pagination, versioning, auth) with an 8-dimension, 40-point rubric in references/.
Add a trust badge to your README
[](https://waxmark.app/items/api-design-review/scan)
--- name: api-design-review description: Reviews a REST or GraphQL API design (OpenAPI spec, GraphQL schema, route handlers, or a written proposal) against a checklist for resource modeling, naming, errors, pagination, versioning, auth, and evolvability, and scores it with the rubric in references/. Use when the user asks to review an API, design endpoints, critique a schema, check an OpenAPI file, or asks "is this a good API". license: CC0-1.0 metadata: author: Waxmark version: "1.0.0" --- # API Design Review Review the contract, not the implementation. The question for every item is: will a client developer who has only the docs do the right thing on the first try, and will we be able to change this in a year without breaking them? ## Procedure 1. **Locate the contract.** Prefer, in order: OpenAPI/Swagger file, GraphQL SDL, route definitions plus DTOs/serializers, a design doc. Say which you are reviewing. If only handlers exist, reconstruct the contract as a table (method, path, request, response, errors) before judging it. 2. **Identify the consumers.** Internal service, first-party web/mobile app, or third parties. Third-party APIs weigh stability and docs higher; internal APIs weigh consistency with sibling services higher. 3. **Walk the checklist** below. For each item record pass, fail, or n/a with a one-line reason and a location (path or type name). 4. **Score** with `references/rubric.md`. Read it before scoring; it defines the levels so two reviewers would land on the same number. 5. **Write the review** in the output format. Lead with the three findings that would be most expensive to fix after launch. ## Checklist (REST) - Resources are nouns, plural, kebab-case or snake_case consistently (`/order-items`, not `/getOrderItems`). - Methods carry semantics: GET safe and idempotent, PUT idempotent full replace, PATCH partial, DELETE idempotent, POST for create and non-idempotent actions. - Status codes are specific: 201 + `Location` on create, 204 on empty success, 400 vs 422 distinguished, 404 vs 403 policy stated, 409 for conflicts, 429 with `Retry-After`. - Errors use one envelope everywhere (RFC 9457 Problem Details or an equivalent with `type`, `title`, `status`, `detail`, and a machine-readable `code`). - Collections paginate (cursor preferred for large or changing sets), filter via query params, and declare a maximum page size. Responses expose `next` cursor or link. - Field names and casing are uniform across all payloads; timestamps are ISO-8601 UTC; money is a string or integer minor units, never a float; IDs are opaque strings. - Nullability and optionality are explicit in the schema; no "sometimes present" fields. - Versioning strategy is stated (URL prefix, header, or additive-only) and a deprecation policy exists. - Auth scheme is declared per operation; least-privilege scopes; no secrets in query strings. - Idempotency keys on POSTs that create money-moving or non-retryable side effects. - Rate limits documented; large writes and long jobs return 202 with a status resource. - Every operation has a summary, a description with at least one example request and response, and all error cases listed. ## Checklist (GraphQL) - Schema-first with descriptions on every type and field. - Mutations are verb-specific (`createOrder`, `cancelOrder`), take a single `input` object, return a payload type with the entity plus `userErrors`. - Connections follow the Relay cursor spec for lists that can grow (`edges`, `node`, `pageInfo`). - Nullability is deliberate: non-null where the server guarantees it; nullable to isolate partial failures. - Global object identification (`Node` interface, `node(id:)`) if clients cache. - Query depth and complexity limits exist; no unbounded list fields without arguments. - Deprecation via `@deprecated(reason:)`; no removal without a sunset window. - N+1 risk noted for every list field that resolves a relation (DataLoader or batched resolver expected). ## Output format ```markdown ## API design review: <name> (<REST|GraphQL>, <consumers>) Score: <N>/40 - <level from rubric> ### Top findings 1. **<item>** (<location>) - <impact> - <fix> 2. ... 3. ... ### Checklist | Area | Result | Location | Note | |---|---|---|---| | Naming | pass | | | | Errors | fail | `POST /orders` 500 on validation | use 422 + problem envelope | | ... | | | | ### Rubric scores | Dimension | Score (0-5) | Why | |---|---|---| | ... | | | ### Questions for the author - ... ``` Keep the review under 80 lines. Put proposed schema fragments in fenced blocks rather than prose.