API Contract Reviewer

Purpose: Review an API design — REST endpoints, OpenAPI spec, or informal description — for consistency, REST principle adherence, security posture, breaking change risk, and developer experience quality. Catches design mistakes before they become permanent.

Invocation

/api-review <spec-or-description>

Accepts:

• OpenAPI YAML or JSON
• Markdown list of endpoints
• Plain English description of the API

Review Dimensions

1. REST Compliance

• HTTP verbs used correctly?
  • GET = read, safe, idempotent
  • POST = create or non-idempotent action
  • PUT = full replace, idempotent
  • PATCH = partial update, idempotent
  • DELETE = remove, idempotent
• Resource names are nouns, not verbs (/users not /getUsers)
• Nested resources used appropriately (/users/{id}/orders vs ?user_id=)
• Status codes appropriate: 201 (created), 204 (no content), 400 (bad request), 401 (unauth), 403 (forbidden), 404 (not found), 409 (conflict), 422 (validation), 429 (rate limit)

2. Consistency Audit

• Naming convention: consistent across all endpoints? (camelCase vs snake_case vs kebab-case)
• Pagination: consistent style on all list endpoints? (cursor vs offset, same field names)
• Error response shape: same structure everywhere?
• Date format: ISO 8601 throughout? (2026-02-20T00:00:00Z)
• ID format: UUID vs integer vs slug — consistent?
• Envelope style: { data: [...] } vs [...] — consistent?

3. Security Review

• Authentication requirements stated for every endpoint?
• Authorization: can users access other users' resources? Is it enforced?
• Rate limiting: mutation endpoints (POST, PUT, DELETE) protected?
• Input validation constraints defined in spec (max lengths, allowed values)?
• Sensitive data in responses? (passwords, tokens, internal IDs, PII)
• Webhook endpoints: HMAC signature verification mentioned?

4. Breaking Change Analysis

If reviewing a v2 or modification to an existing API:

List every breaking change with a migration guide.

5. Developer Experience

• Field names self-documenting? (userId not uid)
• Error messages actionable? ("Email is required" not "invalid input")
• Pagination cursor-based or offset-based? (cursor preferred for large/live datasets)
• Batch endpoints for operations typically done in loops?
• Consistent use of _at suffix for timestamps (created_at, updated_at)?

Output Format

## API Review: [API Name]

### Summary
[2-3 sentence quality assessment]

### Findings

[SEVERITY] Category — METHOD /path
Issue description.
Suggested fix: ...

### Breaking Changes
[List or "None identified"]

### Recommendations
[Prioritized improvements]

### Score: [X/10]

Severity levels:

• CRITICAL — Security hole or data loss risk
• HIGH — Bug that will cause real failures
• MEDIUM — Consistency or DX issue
• LOW — Style or minor improvement

Rules

• Flag every mutation endpoint that doesn't explicitly state its auth requirement
• Unbounded list endpoints (no pagination, no LIMIT) are always rated MEDIUM or higher
• REST violations rated LOW unless they cause real interoperability problems
• Never approve an API that exposes user data from other users without authorization checks
• If the API has no versioning strategy: flag it as MEDIUM and suggest /v1/ prefix