api-contract-reviewer

name	api-contract-reviewer
description	Use this skill to review, audit, or document API contracts and endpoints. MANDATORY TRIGGERS: API review, API design, REST API, GraphQL schema, gRPC proto, OpenAPI, Swagger, endpoint review, API consistency, API audit, routes, controllers. Also use when: checking naming conventions, validating error handling, reviewing versioning strategy, documenting existing API surface, finding inconsistencies across endpoints. Do NOT use for: full architecture review (use architecture-analyzer) or CI/CD pipeline review (use pipeline-auditor).
metadata	{"author":"N.V","version":"1.0"}
context	fork
agent	Explore
allowed-tools	Read, Grep, Glob, Bash

Overview

Reviews API contracts (REST, GraphQL, gRPC) for consistency, completeness, and adherence to best practices. Scans route definitions, controllers, schema files, and middleware to produce a structured API audit report.

When to Use This Skill

• Reviewing an API for consistency before release
• Documenting an existing API surface for the team
• Checking naming conventions, HTTP methods, status codes
• Auditing error handling and validation patterns
• Reviewing versioning strategy
• Preparing an API for public/partner consumption

Workflow

Quick Version (single API layer)

1. Find route definitions or schema files
2. List all endpoints with methods, paths, request/response shapes
3. Check against the consistency checklist
4. Output findings

Full Version (comprehensive API audit)

1. Discover — Glob for route files, controllers, schema definitions, OpenAPI specs
2. Inventory — list every endpoint: method, path, auth, request body, response shape
3. Naming consistency — check resource naming, pluralization, casing conventions
4. HTTP semantics — verify correct methods (GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes)
5. Error handling — check for consistent error response format, proper status codes
6. Validation — check input validation on all write endpoints
7. Auth & permissions — verify auth middleware applied consistently
8. Versioning — check versioning strategy (URL, header, query param)
9. Documentation — check if OpenAPI/Swagger spec exists and matches implementation
10. Generate report — endpoint inventory + findings

Audit Checklist

Naming & Conventions

□ Resource names are plural nouns (/users, /orders, not /getUser)
□ Consistent casing (kebab-case or camelCase, not mixed)
□ No verbs in URLs (use HTTP methods instead)
□ Nested resources follow parent/child pattern (/users/:id/orders)
□ Query params for filtering, sorting, pagination

HTTP Semantics

□ GET — read, no side effects, cacheable
□ POST — create, returns 201 + Location header
□ PUT — full replace, idempotent
□ PATCH — partial update
□ DELETE — remove, returns 204 or 200
□ Correct status codes (400 client error, 500 server error, not everything-is-200)

Error Handling

□ Consistent error response format { error: { code, message, details } }
□ Validation errors return 422 with field-level details
□ 404 for missing resources (not empty 200)
□ 401 vs 403 used correctly (unauthenticated vs unauthorized)
□ No stack traces leaked in production errors

Security

□ Auth required on all non-public endpoints
□ Rate limiting configured
□ Input size limits set
□ CORS configured appropriately
□ Sensitive data not in URL params (use body or headers)

Critical Rules

• Check implementation, not just docs — OpenAPI specs may be out of date
• Rate consistency as a first-class metric — inconsistency confuses API consumers
• Compare similar endpoints — if /users returns { data: [...] }, /orders should too
• NEVER modify any files — this is a review-only skill

Output Format

# API Contract Review: [Project Name]

## API Inventory
| Method | Path | Auth | Request Body | Response | Status |
|--------|------|------|-------------|----------|--------|
| GET | /api/v1/users | JWT | — | User[] | ✅ |
| POST | /api/v1/users | JWT | CreateUserDTO | User | ⚠️ |

## Endpoint Map
\`\`\`mermaid
graph LR
    Client --> Auth[Auth Middleware]
    Auth --> Users[/users]
    Auth --> Orders[/orders]
    Users --> UserService
    Orders --> OrderService
\`\`\`

## Findings

### ⛔ Critical
- **[Finding]** — [endpoint] — [explanation + fix]

### ⚠️ Warning
- **[Finding]** — [endpoint] — [explanation + fix]

### 💡 Suggestion
- **[Finding]** — [endpoint] — [explanation + fix]

## Consistency Score: X/10