api-design-reviewer

Files (12)

• SKILL.md
• api-review-report-template.md · assets/
• openapi.example.json · assets/
• async-and-events.md · references/
• guessability.md · references/
• reliability.md · references/
• requests-responses.md · references/
• resource-modeling.md · references/
• scoring.md · references/
• standards.md · references/
• check_openapi_shape.py · scripts/
• guessability_check.py · scripts/

SKILL.md (first lines)

# API Design Reviewer

## Mission

Review an API as a product, not as a schema. The contract is an interface; developers are its users, and their success is the outcome that matters. OpenAPI syntax is only one surface of the product.

Guessability is the test. **Can a developer with the product's domain vocabulary predict the endpoint, the path parameters, the response shape, the error, and the enum values without reading the docs?** An API that needs documentation for every call has a design defect, not a documentation gap.

Do not repair a confusing API by documenting it. Flag the underlying API defect and attribute it to the surface that owns the fix.

For a surface exposed to agents as tool definitions or an MCP server, hand the tool-surface
review to `agent-integration-dx` if available. This skill owns the HTTP contract beneath it.

Read `references/standards.md` for the canonical thresholds, severity vocabulary, and release gates.

## Two scores, always

Report two independent scores whenever the evidence exists:

- **API DX Score /100** — the API as a product: resource modeling, naming, consistency, guessability, reliability semantics, errors, auth, and versioning.
- **OpenAPI Correctness Score /100** — the contract as a document: structure, refs, response coverage, and examples.

Neither score averages away the other. A perfectly valid OpenAPI file can earn a low API DX score, and a guessable API can ship with a broken spec. Report both; never merge them into one number.

Findings use the canonical P0–P4 severity vocabulary. Every finding carries an owner: **API** (contract design), **Product** (scope and decisions), or **Docs** (documentation and guidance).

## API design review workflow

### 1. Inventory the surface

Collect the contract and the evidence to review it against:

- the API contract: OpenAPI/Proto/AsyncAPI/GraphQL schema or the authoritative definition
- server implementation and tests, when the repository is available
- generated clients, official SDKs, and example code
- existing docs, changelogs, and migration notes

Do not review the contract in isolation when the repository is available. Verify behavior against implementation and tests; never treat the schema as truth when code contradicts it.

Record what was reviewed and what was not. Label findings and scores with evidence: **Observed**, **CI-observed**, or **Estimated**.

### 2. Resource model and naming

Read `references/resource-modeling.md` when evaluating resource boundaries and naming.

Check:

- resources are nouns, collections are plural, actions live in HTTP methods
- identifiers are opaque and consistent across resources
- parent/child relationships use one canonical path form
- state transitions are explicit and documented
- resource boundaries follow the decision tree in the reference

**Do not** accept "documented" as a fix for a confusing model. **Never** approve a path that mixes naming conventions within one API.

### 3. Requests and responses

Read `references/requests-responses.md` when reviewing request and response shapes.

Check:

- required vs optional fields, null vs omitted, defaults, and units
- one canonical timestamp and ID convention across the API
- one envelope and one pagination vocabulary
- filtering, sorting, and field selection are named after the fields they operate on

**Verify:** the same concept (IDs, timestamps, pagination fields, error fields) has one name and one shape everywhere.

### 4. Reliability semantics

Read `references/reliability.md` when evaluating idempotency, retries, timeouts, concurrency, and rate limits.

Check:

- mutating POSTs accept an idempotency key; PUT/DELETE are idempotent by method
- retryable errors are explicit, with `Retry-After` where relevant
- timeouts are documented and end in a definitive status
- concurrency control (ETag/If-Match) exists where writes can race
- rate limits and request/correlation IDs are part of the contract

**Do not** let "the client handles it" cover for an API that never defines retry, timeout, or limit semantics.

### 5. Async operations and events

Read `references/async-and-events.md` when reviewing async operations, webhooks, and event delivery.

Check:

- async operations use 202 plus a job resource, with documented terminal states
- cancellation is explicit and recorded
- webhooks define delivery guarantees, retry schedules, signatures, and event IDs

**Never** approve a webhook with no documented delivery guarantee or signature scheme.

### 6. Errors

Review the error model as a product surface:

- error responses have one stable shape: code, message, details, request ID
- status codes are honest: 4xx for client mistakes, 5xx for server faults, 429 for rate limits, 409 for conflicts
- error codes are unique, documented, and actionable; the message tells the developer what to change
- validation errors identify the failing field and the constraint

**Do not** use 400 for everything. **Never** emit an error body that lacks the request ID a developer needs to report the problem.

### 7. Authentication, authorization, and versioning

Check:

- one primary auth scheme, with scopes and permissions named consistently
- the token lifecycle: issue, refresh, revoke — is explicit
- the versioning strategy is explicit: URL, header, or media type, with documented deprecation and removal policy
- breaking changes are versioned; never mutate an existing contract silently

**Verify:** a developer can predict which credentials and which version they need to make the first successful call.

### 8. Guessability probes

Read `references/guessability.md` before running guessability probes.

From devarispbrown/devex-skills, MIT.

More from devarispbrown/devex-skills