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/.

License: CC0-1.0 · By waxmark · v1 · 2026-11-02

Share on X

Add a trust badge to your README

[![Waxmark](https://waxmark.app/api/badge/api-design-review)](https://waxmark.app/items/api-design-review/scan)
Report
---
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.
API design review with scoring rubric · Waxmark