# API Contract Reviewer

Review an API design for REST compliance, consistency, security, breaking changes, and developer experience. Accepts OpenAPI specs, markdown endpoint lists, or plain descriptions.

## Quick Reference

# 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:

| Change | Breaking? |
|--------|-----------|
| Add new optional field to response | No |
| Add new required field to request | **Yes** |
| Remove field from response | **Yes** |
| Rename field | **Yes** |
| Change field type | **Yes** |
| Change status code | **Yes** |
| Add new endpoint | No |
| Remove endpoint | **Yes** |

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