design-api-review

name	design-api-review
description	Review an OpenAPI specification against API standards and OpenAPI best practices. Point it at a spec — a path on disk, a URL, or a GitHub repo — and it reviews against its own bundled standards and best practices unless you supply yours. Produces a divergence report (verdict per standards section, each finding citing the rule it breaks) for the user to review; fixes are applied only after the user decides. Use when user says "/design-api-review" or asks to review, audit, or check an OpenAPI spec against standards. The spec is the only required input. Does not generate a spec (that is `design-api-spec`) and does not review implementation code.
license	MIT
metadata	{"version":"1.1.0","author":"Emmanuel Paraskakis / Level 250"}

API Design Review

Review an existing OpenAPI specification against an API standards file and an OpenAPI best practices file, and report every divergence with a citation to the exact rule it breaks. This is the fourth skill in Emmanuel Paraskakis's method for designing APIs with LLMs: design-api (end-to-end) → design-api-stories (requirements → stories) → design-api-spec (stories → spec) → design-api-review (spec → standards-compliance verdict). Use it on specs produced outside the method (hand-written, generated by another tool, inherited), on old specs after the standards evolve, or as an independent check on a freshly generated spec.

Review first, fix after. The deliverable is the divergence report. Do not modify the spec until the user has seen the report and said which findings to fix — some divergences are deliberate design decisions, and only the user can tell.

Scope and Routing

Triggering is defined in the frontmatter description. In scope: reviewing an existing OpenAPI spec — supplied as a path, a URL, or a GitHub repo — against a standards ruleset and an OpenAPI best-practices ruleset, defaulting to the bundled ones. Out of scope: generating a spec (use design-api-spec) and reviewing implementation code.

Inputs

Only the spec is required. Ask for it in one line. Do not open a negotiation about the other inputs — they have defaults.

Point me at the OpenAPI spec — a path on disk, a URL, or a GitHub repo. I'll review it against my own standards and OpenAPI best practices, unless you'd rather give me yours.

1. The OpenAPI spec under review (required) — JSON or YAML, any 3.x version. Accept a path on disk, a URL to fetch, or a GitHub repo to find it in. Given a repo rather than a file, locate the spec and name the file you picked before reviewing it.
2. API Standards (optional) — the conventions ruleset. Defaults to references/examples/API-standards.md. A user-supplied file supersedes it; identify it by a heading like # API Standards or # Style Guide.
3. OpenAPI Best Practices (optional) — document-quality ruleset. Defaults to references/examples/OpenAPI-best-practices.md. A user-supplied file supersedes it; identify it by a heading like # OpenAPI Best Practices.
4. Domain model and/or stories (optional) — when provided, also check the spec tells the truth about the domain (property names, enums, relations).

Identify any supplied file by its # Title heading or content, not by filename. Never ask for a ruleset the user did not mention — state which rulesets you used at the top of the report and proceed. If no spec is given, ask for it and stop.

Bundled Rulesets

references/examples/ holds the two default rulesets: API-standards.md and OpenAPI-best-practices.md. No sample spec is bundled — the spec always comes from the user.

Step 1: Read Everything

Read the spec and both rulesets completely. Build the checklist FROM the rulesets you were given, not from memory — the files win over anything you believe about API design, and they evolve. For every numbered rule in the standards and best practices, ask: does the spec comply, diverge, or is the rule not applicable?

Step 2: Sweep the Spec Against Every Standards Section

Walk the standards file section by section (typical sections below — use whatever sections the provided file actually has):

• Casing — one convention per surface: JSON fields, query params, path segments and template params, headers, enum values. Check EVERY field, parameter, and path in the spec against the table.
• Naming — standard vocabulary (createdAt not creationDate, bare-adjective booleans), no invented language, no over-qualification, industry-standard terms.
• Paths & Resources — no /api or /v1 base unless specified, no trailing slashes, pluralized resources, nesting depth, item-level operations flat, every collection has a list endpoint.
• Methods & Status Codes — 201+Location for creation, 204 for DELETE, PUT over PATCH, correct 400 vs 409, 401 vs 403, 404 semantics (never for an empty collection), 429, 500.
• IDs & References — UUID default (deviations must be justified in the spec), <resource>Id reference fields, no URLs as references, credentials never in URLs.
• Properties — standard attributes (id, createdAt, updatedAt) unless justified, enums over strings, open-enum tolerance, no null emission without meaning.
• Requests & Responses — JSON only, wrapper on every collection (data + meta), totalCount present, focused response shapes, money as decimal string + currency.
• Query Parameters & Pagination — camelCase matched case-insensitively, field=value filters, comma-separated multi-values, offset/limit with documented default and max, stable default sort, no cursor pagination unless required.
• Errors — RFC 9457 Problem Details on application/problem+json, standard fields, field-level errors array for validation, one-try recovery quality of title/detail.
• Rate Limiting — the headers the standards mandate, on the responses they mandate; Retry-After on 429.
• Security — auth scheme matches the standards' allowed list (e.g. Bearer, never X-Api-Key, never Basic, never credentials in URLs), 401 defined for every authenticated operation, 403 where permissions apply.
• Versioning & Deprecation — no version in path unless justified, deprecation headers plan if anything is deprecated.

Then sweep the best-practices file the same way (descriptions and examples everywhere, summaries + operationIds, tags, contact/license/servers, components extraction, no inline schemas, no orphans, map-structure integrity, absolute URIs, semantic completeness of operation descriptions — including whatever agent-readiness rules the file contains).

Step 3: Classify Every Finding

Three verdicts, one per finding:

• DIVERGES — breaks a rule with no stated justification. Cite the rule (section + number), show the offending spec location, propose the concrete fix.
• DELIBERATE — breaks a rule but the spec documents why (in a description, or the user has said so). Cite both the rule and the justification. These are surfaced, not fixed — the user may still overrule.
• UNJUSTIFIED-DELIBERATE — the spec deviates in a way that looks intentional but carries no documented reason. The fix may be either changing the spec OR documenting the reason — user's call.

Do not pad the report: full compliance with a section is one line ("Casing: compliant"), not a table of everything that's fine.

Step 4: Report

Deliver the report in this shape:

## API Design Review: [spec title] v[version]

**Spec:** [path / URL / repo + file you picked]
**Reviewed against:** [standards file] + [best-practices file] — [bundled defaults | supplied by user]

**Verdict: [COMPLIANT | N divergences (X to fix, Y deliberate, Z to decide)]**

### Diverges (proposed fixes)
1. [Location] breaks [Standards § / rule N]: [what] → fix: [concrete change]

### Deliberate (documented, no action unless overruled)
1. [Location] deviates from [rule]: [the documented justification]

### Needs a decision
1. [Location]: [the deviation, the two options]

### Compliant sections
[one line listing them]

Order findings by severity: security and error-contract issues first, naming/cosmetic last.

Step 5: Fix (only after user review)

When the user says which findings to fix, apply them to the spec, then:

1. Re-validate JSON and $ref integrity.
2. If RMOA_API_KEY is available, re-lint with RateMyOpenAPI (see the design-api-spec skill, "Lint with RateMyOpenAPI") and confirm the score did not regress.
3. Show a diff-level summary of what changed.

Key Principles

1. The rulesets in play are the law. Review against the files you actually loaded — the user's when supplied, the bundled defaults otherwise — never against memorized API lore. If the standards file and your instincts disagree, the file wins. Name the rulesets in the report so the reader knows which law was applied.
2. Cite or it didn't happen. Every finding names the exact rule it breaks. A finding that can't cite a rule is an opinion — leave it out or label it explicitly as a suggestion.
3. Deliberate deviation is legitimate. Standards themselves permit deviation with good reason. The review's job is to make every deviation visible and justified, not to enforce uniformity.
4. Report before repair. The user decides what gets fixed. Never silently "improve" a spec while reviewing it.
5. The spec is the contract. In spec-first workflows the implementation follows the spec, so a spec error becomes a code error. Review severity reflects that.