API Design

REST API Design Review

Quick Reference

§1 Scope

In scope — REST API contract design and review:

• Resource modeling (URL structure, naming, hierarchy)
• HTTP method semantics (GET/POST/PUT/PATCH/DELETE)
• Status code selection (2xx/4xx/5xx semantic correctness)
• Error model design (machine-parseable codes, field-level details)
• Pagination, filtering, sorting, search patterns
• Idempotency (Idempotency-Key header, retry safety)
• Concurrency control (ETag, If-Match, optimistic locking)
• Auth/AuthZ per endpoint, IDOR prevention
• Rate limiting (per-actor, 429 + Retry-After)
• Versioning, backward compatibility, deprecation planning
• OpenAPI/Swagger contract generation

Out of scope — delegate to dedicated skills:

• API integration testing → api-integration-test
• gRPC/Protobuf design → separate skill
• Application code implementation → go-code-reviewer

§2 Rule Nature and Finding Severity

Most API "best practices" are house conventions, not protocol requirements. Reporting a convention deviation with the same force as a security hole destroys the signal. But "how binding is this rule" and "how bad is this instance" are two different questions, and collapsing them into one tag is what makes two reviewers reach two verdicts.

2.1 Rule nature — a static property of the rule

Every rule in §6 carries exactly one nature tag. Nature answers why the rule exists. It does not by itself determine severity.

For a [C] rule the review asks "was a policy chosen and written down?" — never "was my preferred option chosen?" Disagreeing with a stated, consistently applied policy is never a finding.

2.2 Risk triggers — conditions that change what is at stake

A trigger does exactly one of two things, and never lowers an obligation:

• Raises severity of a [D] or [C] finding — an unstated write-conflict policy is a WARN in general and a FAIL under T4, because a lost update now costs something real.
• Adds an obligation to a rule of any nature — T6 adds data minimization to the [P] rule in item 5. A trigger attached to a [P] rule is normal: [P] rules can grow requirements under risk, they just never shrink.

If you cannot tell whether a trigger applies, record that in §9.9 and score the item N/A. Do not assume the strict reading.

2.3 Where severity is decided

Severity is not a property of the nature tag. It is a function of (nature × what is actually wrong × which triggers are live), and it is defined in exactly one place: the table in §8. Do not restate a severity ceiling here — two severity tables drift, and the reader then cannot tell which one binds.

§3 Mandatory Gates

Execute gates in order. Each gate has a STOP condition.

Gate 1: Scope Classification

STOP: Request is not API design (e.g., database query optimization). Redirect to the appropriate skill.

PROCEED: Mode selected. The mode determines whether Gate 2 can stop you.

Gate 2: Consumer & Use-Case

Mode rule — this is the only correct reading of an unknown consumer:

PROCEED: mode known, and either consumer context is known or review-mode degradation is declared.

Gate 3: Risk Classification (change risk)

STOP: Any UNSAFE change without a migration plan.

PROCEED: Every change has a risk level and a mitigation.

Gate 4: Output Completeness

Before delivering, verify all §9 Output Contract sections are present. §9.9 Uncovered Risks must never be empty.

§4 Depth Selection

Force Standard or higher when any signal appears: pagination/filtering design, idempotency requirement, versioning discussion, breaking change assessment, public API, multi-consumer API, any risk trigger T1–T6.

§5 Degradation Modes

When context is incomplete, degrade explicitly — never guess consumer requirements, and never silently upgrade an assumption into a finding.

Hard rules:

• Never claim an API is "backward compatible" without reviewing the actual existing contract.
• In Degraded/Minimal mode, list every assumption in §9.9, and mark unassessed scorecard items N/A — never FAIL.

§6 Design Checklist

Execute every item. Mark PASS / WARN / FAIL / N/A with evidence. Each item shows its nature tag (§2.1) and the scorecard item it feeds (§8), or — if unscored. Severity comes from §8.1, never from the tag alone.

6.1 Resource Model

1. [D] Resource naming & hierarchy → H1. Plural nouns, lowercase, kebab-case: /users, /order-items. No verbs in URLs except explicit action sub-resources (/orders/{id}/cancel). Nesting reflects ownership (/users/{id}/orders); prefer ≤2 levels, more only when every level is part of the authorization boundary. A codebase-wide alternative convention that is applied consistently is a PASS with a note — consistency beats this default.

2. [P] Method & success-status semantics → S1. GET is safe (no side effects). PUT is a full replace and idempotent; PATCH is partial. DELETE is idempotent. POST is not idempotent. For a successful DELETE, RFC 9110 §9.3.5 permits 202 (accepted, not yet enacted), 204 (enacted, nothing to return), or 200 (enacted, body describes the status) — all three are legal; the requirement is that the contract states which one and is consistent per resource class.

   The Code column is [P]: sending 200 where the semantics call for 4xx is a defect. The Also send column is mostly [D] — read the force marker on each row before reporting it. Only rows marked [P] are protocol requirements.

   Situation	Code	Also send	Force
   GET / PUT / PATCH success with a body	200	—	—
   POST created a resource	201	Location. RFC 9110 §15.3.2: if Location is absent the target URI identifies the new resource, so its absence is a usability miss, not a violation	[D]
   Accepted, not yet enacted	202	a status monitor to poll. RFC 9110 §15.3.3 says the response "ought to" point to one — strong advice, not a MUST	[D]
   Success with nothing to return	204	no body at all	[P]
   Malformed JSON in the body	400	a parse-error code	[D]
   Not authenticated	401	re-login can fix this	[P]
   Authenticated, not permitted	403	re-login cannot fix this — see item 7	[P]
   Absent, or existence withheld	404	see item 7	[P]
   State conflict, duplicate key	409	—	—
   Precondition failed (If-Match)	412	—	[P]
   Deliberately removed after sunset	410	410 says "was here, deliberately gone"; 404 is still legal	[D]
   Semantically invalid field values	422	field-level details[]. RFC 9110 §15.5.21 defines 422 as "syntax correct, instructions unprocessable" — it does not mandate 422 for validation, and a consistent 400 is a valid house convention	[D]
   Rate limited	429	Retry-After. RFC 6585 §4 says the response MAY include it — recommend it, never fail on it	[D]
   Unexpected server error	500	log it, never expose it	[P]

   Never swap 401 and 403 — the distinction is the whole signal a client needs to decide whether retrying with fresh credentials is worth it. That one is [P].

6.2 Safety & Authorization

3. [P] Error transport integrity → C2. Four properties, and only these four are invariants:

   • the failure carries a non-2xx status — never 200 {"success": false}, because proxies, caches, browsers and client HTTP libraries branch on the status line, not on your body;
   • the body carries a stable machine-identifiable discriminator that clients can switch on without string-matching prose;
   • the same shape is used by every endpoint in the API;
   • nothing sensitive leaks (item 5).

   These are satisfied by more than one concrete format. An API that returns application/problem+json per RFC 9457 — type/title/status/detail/instance plus extensions — satisfies all four, with type as the discriminator. So does a gRPC google.rpc.Status. Do not FAIL a consistent RFC 9457 API for not using the envelope in item 4. The invariant is the four properties; the field names are item 4's default.

4. [D] Default error envelope → — (report only). Absent an existing house standard, use {error: {code, message, details[], trace_id}}: code stable and snake_case, message human-readable and re-wordable, trace_id correlating to server logs. Any consistent alternative — RFC 9457 being the obvious one — is a PASS with a note. What fails is a different shape per endpoint, which is item 3's third invariant, not this rule. Load references/error-model-patterns.md for the standard code list.

5. [P] No internal or sensitive data in responses → C3 · Triggers: T6. Never return stack traces, SQL text, driver messages, internal hostnames, file paths, or credentials. Also keep server-side observability out of the client contract: metric names, audit subject/tenant/role, and permission-evaluation traces belong in your logs and audit sink, keyed by trace_id. Echoing them back leaks authorization state to the caller and couples the client contract to internal monitoring names. Under T6 two further requirements bind: return only the regulated fields the caller actually needs (data minimization — a full record because "the client might want it" is a disclosure), and never echo a submitted regulated value back inside details[] of a validation error.

6. [P] Object-level authorization is performed → C1. Every endpoint that reaches a resource by ID MUST verify that this caller may reach that specific resource — ownership, tenant scope, or role. GET /users/{id} must not serve another user's record merely because the request is authenticated. This is OWASP API Security #1 (Broken Object Level Authorization). The check is the non-negotiable part; the status code returned on denial is item 7.

7. [C] Denial status policy → — (report only). Both 403 and 404 are legitimate; OWASP accepts either, and forbids only 200. Choose by whether the resource's existence is confidential:

   • 404 when existence itself is secret — enumerable IDs, cross-tenant resources, per-user objects in a shared ID space.
   • 403 when existence is not secret and a clear denial aids the caller — a teammate lacking a role on a known shared resource, admin tooling, internal APIs.
   • Consistency is the security property. Mixing 403 and 404 across one resource class is the enumeration oracle you were trying to close. Log both identically server-side.

8. [C] Retry-safety policy for mutations → S2 · Triggers: T1, T2, T3. A POST or action endpoint whose replay would double-charge, double-allocate, or re-send needs a stated answer to "what happens on retry". Valid options include an Idempotency-Key header, a client-supplied natural key the server dedupes on, an exactly-once consumer, or a documented "replays are harmless here". Under T1/T2/T3 having no stated answer is a FAIL; elsewhere it is a WARN, and an append-only endpoint with no external effect is a PASS. If you choose Idempotency-Key, production-grade keys need: (a) scope — tenant + subject + method + path, so two callers cannot collide; (b) request fingerprint — same key with a different body → 409; (c) TTL — default 24h, chosen as max client retry window + clock skew; (d) replay indicator — X-Idempotent-Replayed: true on a cache hit.

9. [C] Write-conflict policy → S2 · Triggers: T4. Concurrent updates resolve either by optimistic locking (ETag + If-Match, 412 on mismatch) or by last-write-wins. LWW is a legitimate choice, and the reportable failure is an unstated policy — never the absence of ETag. Under T4 apply §8.1 by asking which of three things is true, in this order:

   • No policy stated → FAIL. Nobody knows what a concurrent write does.
   • A policy is stated and its premise holds → PASS. Including "multi-writer, LWW, lost updates accepted because the field is advisory and the user sees current state on reload." You may record the risk; you may not fail it.
   • A policy is stated but the design contradicts its premise → FAIL. "LWW is safe because only the owner writes this record", on a record a batch job also writes, is a false premise, not a preference. Name the second writer as the evidence.

   Without T4 the same three cases are FAIL / PASS / WARN respectively.

10. [P] Input validation is specified → S3. Every request field has a declared type, required/optional status, and bounds. Undefined behaviour for a missing required field is a contract gap, not an implementation bug (see AE-6). Which rejection code carries a validation failure is [D], not part of this rule — see the status table in item 2: 422 with details[] is this skill's default and a consistent 400 is an equally valid house convention. What this rule requires is that the contract defines the rejection behaviour at all, and that caller error never surfaces as 5xx.

6.3 Query & Pagination

11. [D] Pagination bounded and stable → S4 · Triggers: T5. Cursor-based for large or high-churn datasets; offset-based for small, searchable, or page-numbered admin UX. Enforce a server-side max limit. Always sort on a stable key — append a unique tie-breaker (e.g. id) so page boundaries are deterministic when the primary sort key has duplicates.

12. [D] Filtering, sorting, and search constrained → H3. Only allowlisted fields may be filtered or sorted; reject unknown fields with 400 + error code. Never interpolate filter values into a query. Keep full-text search on its own q parameter or /search endpoint rather than overloading filter params.

6.4 Compatibility & Operations

13. [P] Every change classified breaking or non-breaking → S5. Non-breaking: add optional response fields, add endpoints, add optional query params, relax validation. Breaking: remove/rename fields, change types, tighten validation, change status-code semantics, add a required request field.

    Field order is not on either list by default. RFC 8259 §1 defines a JSON object as an unordered collection of name/value pairs, so reordering fields is not a breaking change for any spec-conformant consumer. It does change the serialized byte sequence — Go's encoding/json (and sonic) emit struct fields in declaration order — which matters in exactly two cases:

    • a named consumer parses the body by position or string-prefix rather than by key (record it as that consumer's non-conformance, with its identity, not as a property of JSON);
    • the raw body feeds a byte-exact artifact — response signature/digest, HMAC, content-addressed cache key, or golden-file test.

    Absent one of those two, classify a reorder as non-breaking. Load references/compatibility-rules.md for the full matrix.

14. [D] OpenAPI elements complete → H2. Paths, methods, parameters, request/response schemas per status code, error codes, auth requirements. Keep a baseline spec in CI and diff each PR against it to catch removed paths, removed fields, and type changes automatically.

15. [C] Rate-limit policy → H4 · Triggers: T5. Valid options run from a per-actor quota returning 429 (with Retry-After recommended — RFC 6585 §4 makes it a MAY, so never fail on its absence) through to an explicit "no limit; capacity bounded by the upstream gateway". Under T5 no stated policy is a FAIL; for trusted internal callers it is a WARN. What is reportable is silence — nobody knowing whether a limit exists — never the option chosen.

16. [C] Operational contract documented → — (report only). If the service exposes health/readiness endpoints or middleware, state the shape: a liveness probe (GET /healthz — is the process alive) split from a readiness probe (GET /readyz — are dependencies reachable), whether those probes are authenticated (unauthenticated probes are simpler but disclose service state — a threat-model call), and middleware order. A common ordering is Recovery → CORS → Logging → RateLimit → Auth → Handler, because CORS preflight carries no token and rate limiting should absorb credential brute-force before auth. Deviations are fine when argued against those reasons.

§7 Anti-Examples

AE-1: Verb in URL

WRONG: POST /api/v1/createUser
RIGHT: POST /api/v1/users

Resources are nouns. The HTTP method IS the verb.

AE-2: 200 for everything

WRONG: HTTP 200 {"success": false, "error": "not found"}
RIGHT: HTTP 404 {"error": {"code": "not_found", "message": "User not found"}}

Status codes exist for machines. Wrapping errors in 200 breaks HTTP semantics, caching, and client error handling.

AE-3: Unstructured error messages

WRONG: HTTP 400 {"message": "Something went wrong"}
RIGHT: HTTP 422 {"error": {"code": "validation_error", "message": "Validation failed", "details": [{"field": "email", "code": "invalid_format"}]}}

Without a stable code, clients can only match on message strings — which break on wording changes.

AE-4: Replayable money-moving POST

WRONG: POST /payments — no Idempotency-Key → network retry double-charges the customer
RIGHT: POST /payments with Idempotency-Key: "req-abc-123" → retry returns the original response

Binding under T1–T3 (§2). A POST /audit-log-entries with no external side effect does not need this.

AE-5: No object-level authorization (IDOR)

WRONG: GET /users/456 — returns data whenever the caller is authenticated (any user reads any user)
RIGHT: GET /users/456 — server verifies caller is user 456 or holds an admin role, then serves or denies

OWASP API Security #1. Authentication != authorization. The denial status (403 or 404) is a separate policy choice — see §6 item 7 and AE-13.

AE-6: Design issue reported as implementation bug

WRONG: "Bug: API returns 500 when email is missing"
RIGHT: "API design gap: POST /users lacks input validation spec — no defined behavior for missing required fields"

Extended anti-examples (AE-7 through AE-14) in references/api-anti-examples.md.

§8 API Design Scorecard

Score 12 items. Unassessed items in Degraded/Minimal mode are N/A, never FAIL.

8.1 Severity — the single decision table

This is the only place severity is defined (§2.3). Read the row for what is actually wrong; the nature tag alone never decides the outcome.

Only a trigger that the rule itself declares moves it between the last two columns. Each §6 rule states its own triggers (Triggers: T4); a rule that declares none is always read in the "no applicable trigger" column. T1 being live somewhere in the API does not escalate an unrelated naming deviation.

WARN never fails its scorecard item; it is reported and carried to §9.9. FAIL fails it.

The falsified-premise row is not a back door for overruling the owner's choice. It fires only when the API's own justification is untrue — "last-write-wins is safe here because only the owner writes this record", on a resource the design shows two writers reaching. That is a factual contradiction you can point at, not a preference. An owner who writes "multi-writer, last-write-wins, we accept lost updates because the field is advisory" has stated a policy whose premise holds: PASS, with the trade-off recorded.

What a [C] rule can and cannot cause. A [C] rule can fail its item only through silence under a live trigger — never through the choice made. Because S2 is fed by [C] rules, an unstated write-conflict policy under T4 can consume one of the five Standard slots, and combined with another Standard failure that can produce an overall FAIL. That is intended: an unanswered concurrency question on a genuinely contended resource is a real defect. What cannot happen is an overall FAIL caused by disagreeing with a stated policy, and no [C] rule feeds a Critical item, so contextual judgement can never trip the any-FAIL tier.

Critical — any FAIL means overall FAIL

Security and protocol integrity only. Nothing cosmetic belongs in this tier.

• C1 Object-level authorization performed on every resource-by-ID endpoint (item 6)
• C2 Failures carry a non-2xx status and a stable machine-identifiable discriminator, in one shape across the API — any consistent format, RFC 9457 included (item 3)
• C3 No internal implementation detail, authorization state, or sensitive data in responses (item 5)

Standard — 4 of 5 must pass

• S1 HTTP method and success-status semantics correct (item 2)
• S2 Retry safety and write-conflict policy specified where risk triggers apply (item 8, item 9)
• S3 Input validation specified per endpoint (item 10)
• S4 Pagination bounded with a stable sort key (item 11)
• S5 Every change classified breaking or non-breaking (item 13)

Hygiene — 3 of 4 must pass

• H1 Resource naming and hierarchy consistent (item 1)
• H2 OpenAPI elements complete with a CI contract baseline (item 14)
• H3 Filtering, sorting, and search constrained to allowlists (item 12)
• H4 Rate-limit policy stated — including an explicit "none needed" (item 15)

Verdict: X/12; Critical: Y/3; Standard: Z/5; Hygiene: W/4. PASS requires: Critical 3/3 AND Standard ≥4/5 AND Hygiene ≥3/4. N/A items are excluded from both numerator and denominator; report the reduced denominator explicitly.

Report-only rules (never scored, always surfaced in §9.9 when undocumented): default error envelope (item 4), denial status policy (item 7), operational contract (item 16). Item 4 is deliberately unscored: deviating from the house envelope is a [D] matter, and a consistent RFC 9457 API must not lose a Critical point for it.

§9 Output Contract

Every API design review MUST produce these sections. Write "N/A — [reason]" if inapplicable.

### 9.1 Context Gate
| Item | Value | Source |   ← include mode, consumer type, risk triggers found

### 9.2 Depth & Mode
[Lite/Standard/Deep] × [review/design/governance] × [Full/Degraded/Minimal/Planning] — [rationale]

### 9.3 Endpoint Contract Table
| Method | Path | Purpose | Auth | Idempotent |

### 9.4 Request/Response Design
- Per-endpoint: request schema, response schema, status codes, validation rules

### 9.5 Error Model
- Standard error codes + examples per endpoint

### 9.6 Pagination/Filtering Policy (Standard/Deep)

### 9.7 Compatibility Assessment (Standard/Deep)
- Breaking vs non-breaking classification per change
- Migration/deprecation plan if breaking

### 9.8 OpenAPI Spec Elements

### 9.9 Uncovered Risks (MANDATORY — never empty)
| Area | Reason | Impact | Follow-up |

Finding format — every finding carries its nature tag, the triggers that were live, and the severity §8.1 assigns, so a reader can re-derive the verdict: [P|D|C] <scorecard id or —> <triggers or none> <PASS|WARN|FAIL|N/A> — <evidence>

Volume rules:

• FAIL: always fully detailed
• WARN: up to 10; overflow to §9.9
• PASS: summary only
• §9.9 minimum: every assumption, every item left N/A for an unknown trigger, every undocumented [C] policy

Scorecard summary (append after §9.9):

Scorecard: X/12 — Critical Y/3, Standard Z/5, Hygiene W/4 — PASS/FAIL
Risk triggers: [T1..T6 present, or none identified]
Data basis: [full context | degraded | minimal | planning]

§10 Reference Loading Guide