# 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 ``` **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 ## Playground

Input: OpenAPI excerpt

POST /api/skills
requestBody:
  content:
    application/json:
      schema:
        type: object
        properties:
          title: {type: string}
          content: {type: string}

Output: Contract review

🔴 No required fields declared
Both title and content must be
required. Add:
  required: [title, content]

🔴 No maxLength on content
Unbounded string → DoS via huge
payloads. Add maxLength: 50000

🟡 Missing 401 / 422 responses
Document error cases so clients
know what to expect on bad input.

🟡 No description on properties
Add description: fields for SDK
and docs auto-generation.