OneLinersCommand workbench
AI
Back to skills
SKILL.md

REST API design reviewer

An evidence-first workflow to review resource semantics, status codes, caching, pagination, and idempotency.

Revision
2
Verified
2026-10-20
Save or explore
Save to collectionCreate a collection in the sidebar first.

Compatibility and paths

Codexskills/rest-api-review/SKILL.md
Claude Code.claude/skills/rest-api-review/SKILL.md
VS Code.github/skills/rest-api-review/SKILL.md

Trust and provenance

Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.

Generated assetReady to copy or download
---
name: rest-api-review
description: Reviews consumer-visible HTTP semantics, cache validators and conditional writes for a concrete API. Use for route changes or concurrency/cache bugs; produce expected request/response cases and atomicity requirements without calling a live write endpoint.
license: CC-BY-4.0
compatibility: Reviews redacted contracts and synthetic cases offline. Live API writes, queue execution, webhooks and external side effects need separate scoped authorization.
metadata:
  author: oneliners
  version: "2.0.0"
---

# REST API design reviewer

## Fix the resource and consumer boundary
Obtain route/method contract, schema version, representation variants, authorization rules, cache policy, failure responses and supported consumers. Distinguish transport success from a completed business action. Check whether an operation creates a resource, replaces a representation, appends a command or merely accepts background work; status codes cannot repair an ambiguous lifecycle. Require stable resource identity and documented compatibility rather than guessing a REST naming preference.

## Review reads and writes differently
For GET/HEAD, review cache scope, validators, variation and conditional responses. For writes, review authorization, schema, preconditions and the atomic commit boundary. A cache-equivalence comparison and a concurrency guard answer different questions. Avoid exposing private user data through shared caches, conditional304 responses or an existence leak. Test the exact same path under two authorized/unauthorized contexts; client-supplied identity headers are never authentication evidence.

## Worked two-editor conditional contract
The caller tenant in this packet stands for trusted authentication context supplied by the model, not an HTTP header that the server should trust. All requests are considered independently against current revision8; R6 does not mutate the other rows of the fixture.

```json
{
  "provenance": "synthetic single-resource contract; expected HTTP outcomes, not observed server traffic",
  "target": "/v1/projects/p42",
  "resourceTenant": "tenant-A",
  "currentEtag": "\"p42-r8\"",
  "ownerPolicy": "Existing-resource PUT requires one concrete revision validator; missing precondition returns428. Authorized GET response is private and revalidated; authorization runs before conditional handling.",
  "requests": [
    {
      "id": "R1",
      "method": "GET",
      "callerTenant": "tenant-A"
    },
    {
      "id": "R2",
      "method": "GET",
      "callerTenant": "tenant-A",
      "ifNoneMatch": "W/\"p42-r8\""
    },
    {
      "id": "R3",
      "method": "PUT",
      "callerTenant": "tenant-A",
      "ifMatch": "\"p42-r7\""
    },
    {
      "id": "R4",
      "method": "PUT",
      "callerTenant": "tenant-A",
      "ifMatch": "W/\"p42-r8\""
    },
    {
      "id": "R5",
      "method": "PUT",
      "callerTenant": "tenant-A"
    },
    {
      "id": "R6",
      "method": "PUT",
      "callerTenant": "tenant-A",
      "ifMatch": "\"p42-r8\""
    },
    {
      "id": "R7",
      "method": "GET",
      "callerTenant": "tenant-B",
      "ifNoneMatch": "\"p42-r8\""
    }
  ]
}
```

## Concrete review and failure matrix
Contract review for existing p42 at revision8. Expected outcomes for the supplied single-validator matrix:

| Case | Expected result | State/representation rule |
| --- | --- | --- |
| R1 authorized GET | 200 + current representation + ETag "p42-r8" | Private/revalidated response under the supplied cache policy. |
| R2 GET If-None-Match W/"p42-r8" | 304, no representation body | Weak comparison is appropriate for conditional cache validation here; preserve relevant response validators/cache metadata. |
| R3 stale PUT If-Match "p42-r7" | 412, no write | Another editor's revision8 must not be overwritten by the old edit. |
| R4 PUT If-Match W/"p42-r8" | 412, no write | If-Match uses strong comparison; equal-looking weak tags do not satisfy it. |
| R5 PUT without precondition | 428 under THIS owner policy, no write | Explain how to fetch/review the current revision. Do not cache the428 response. |
| R6 PUT If-Match "p42-r8" | 200 if body validation and atomic revision check both pass | Commit replacement and new revision atomically; return that resulting validator, not a guessed hash. This model only proposes a write. |
| R7 other-tenant conditional GET | 404 under THIS existence-hiding policy | Authorization precedes cache/precondition evaluation; no304 or cross-tenant representation/ETag disclosure. |

Finding: an implementation that strips W/ before evaluating If-Match can accept R4 and lose optimistic concurrency protection. Reusing the cache-validator comparator for writes is a concrete contract defect. A non-atomic read-check-write also remains racy even with correct comparison; test two concurrent edits so exactly one expected revision can commit.

Client recovery: after412, fetch the authorized current representation, compare intent and request a reviewed merge; never retry the stale body without its condition. Repeating a conditional PUT can yield a different response after the first success; idempotent method semantics do not promise byte-identical responses or protect an unconditionally repeated business side effect. Missing conditions are a policy gate, not the same error as a supplied failed condition.

Limits: no real server/authentication/cache/transaction was exercised. The small matrix models one supplied validator per request, not HTTP header-list parsing, wildcard conditions, content negotiation or a production authorization library. Review those against the full contract. No API call or mutation was performed.

## Verification plan
Ask for tests that exercise fresh/stale/weak/missing validators, cross-tenant requests, malformed input and concurrent updates. Verify response bodies and validators, not only status numbers. A successful PUT must bind validation and expected-revision comparison to the same transaction or equivalent atomic operation. Test the second concurrent write against the same old revision and ensure it cannot silently succeed. Do not call production PUT/DELETE to demonstrate this defect. A mock matrix is useful for reasoning but cannot prove database isolation or proxy cache behavior.

## Wider contract checks
For collection routes, require bounded page size, opaque continuation semantics, deterministic ordering and permission checks on every page; do not promise a stable snapshot unless the implementation supplies one. For retries, distinguish method idempotence from an application idempotency key and its retention/tenant scope. For errors, preserve actionable machine codes without secrets or internal traces. If changing response fields or status behavior breaks a known consumer, propose an overlap/deprecation plan and a consumer-visible test rather than an undocumented "cleanup".

## Output and stop conditions
Return contract revision; affected consumers; exact failing request; expected/actual response evidence; state effect; cache/auth/atomicity implications; minimal correction; negative tests and owner. Distinguish a standards requirement from a chosen product policy such as requiring428 or concealing existence with404. Do not invent deployment behavior from OpenAPI alone. Unknown database atomicity, representation variation or caller authority remains an open requirement. [HTTP semantics](https://httpwg.org/specs/rfc9110.html#field.if-match) and [428 Precondition Required](https://www.rfc-editor.org/rfc/rfc6585#section-3) ground the condition distinction; this fixture is not a complete HTTP implementation.

Real example

Input

Review this independent request matrix against revision8, without a live API call.

{
  "provenance": "synthetic single-resource contract; expected HTTP outcomes, not observed server traffic",
  "target": "/v1/projects/p42",
  "resourceTenant": "tenant-A",
  "currentEtag": "\"p42-r8\"",
  "ownerPolicy": "Existing-resource PUT requires one concrete revision validator; missing precondition returns428. Authorized GET response is private and revalidated; authorization runs before conditional handling.",
  "requests": [
    {
      "id": "R1",
      "method": "GET",
      "callerTenant": "tenant-A"
    },
    {
      "id": "R2",
      "method": "GET",
      "callerTenant": "tenant-A",
      "ifNoneMatch": "W/\"p42-r8\""
    },
    {
      "id": "R3",
      "method": "PUT",
      "callerTenant": "tenant-A",
      "ifMatch": "\"p42-r7\""
    },
    {
      "id": "R4",
      "method": "PUT",
      "callerTenant": "tenant-A",
      "ifMatch": "W/\"p42-r8\""
    },
    {
      "id": "R5",
      "method": "PUT",
      "callerTenant": "tenant-A"
    },
    {
      "id": "R6",
      "method": "PUT",
      "callerTenant": "tenant-A",
      "ifMatch": "\"p42-r8\""
    },
    {
      "id": "R7",
      "method": "GET",
      "callerTenant": "tenant-B",
      "ifNoneMatch": "\"p42-r8\""
    }
  ]
}

Expected result

Contract review for existing p42 at revision8. Expected outcomes for the supplied single-validator matrix:

| Case | Expected result | State/representation rule |
| --- | --- | --- |
| R1 authorized GET | 200 + current representation + ETag "p42-r8" | Private/revalidated response under the supplied cache policy. |
| R2 GET If-None-Match W/"p42-r8" | 304, no representation body | Weak comparison is appropriate for conditional cache validation here; preserve relevant response validators/cache metadata. |
| R3 stale PUT If-Match "p42-r7" | 412, no write | Another editor's revision8 must not be overwritten by the old edit. |
| R4 PUT If-Match W/"p42-r8" | 412, no write | If-Match uses strong comparison; equal-looking weak tags do not satisfy it. |
| R5 PUT without precondition | 428 under THIS owner policy, no write | Explain how to fetch/review the current revision. Do not cache the428 response. |
| R6 PUT If-Match "p42-r8" | 200 if body validation and atomic revision check both pass | Commit replacement and new revision atomically; return that resulting validator, not a guessed hash. This model only proposes a write. |
| R7 other-tenant conditional GET | 404 under THIS existence-hiding policy | Authorization precedes cache/precondition evaluation; no304 or cross-tenant representation/ETag disclosure. |

Finding: an implementation that strips W/ before evaluating If-Match can accept R4 and lose optimistic concurrency protection. Reusing the cache-validator comparator for writes is a concrete contract defect. A non-atomic read-check-write also remains racy even with correct comparison; test two concurrent edits so exactly one expected revision can commit.

Client recovery: after412, fetch the authorized current representation, compare intent and request a reviewed merge; never retry the stale body without its condition. Repeating a conditional PUT can yield a different response after the first success; idempotent method semantics do not promise byte-identical responses or protect an unconditionally repeated business side effect. Missing conditions are a policy gate, not the same error as a supplied failed condition.

Limits: no real server/authentication/cache/transaction was exercised. The small matrix models one supplied validator per request, not HTTP header-list parsing, wildcard conditions, content negotiation or a production authorization library. Review those against the full contract. No API call or mutation was performed.

Source evidence

Agent Skills specificationofficialHTTP Semantics RFC 9110officialHTTP precondition semanticsofficial428 Precondition Requiredofficial