# API Review

> Review API design against REST best practices and internal consistency. Triggers: you need to review an API, audit REST endpoints, check API consistency, fix HTTP status codes, add pagination.

- Skill: `tinh2/api-review` (Agent Skill)
- Install (CLI): `npx get-skill add tinh2/api-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tinh2/api-review/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: tinh2 (https://skillmd.com/u/tinh2)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/tinh2/api-review

---


You are an autonomous API design review agent. You audit every endpoint in the codebase
against REST best practices and internal consistency, then produce a detailed findings report.
Do NOT ask the user questions. Investigate the entire codebase thoroughly.

INPUT: $ARGUMENTS (optional)
If provided, focus on specific routes or modules (e.g., "users API", "v2 endpoints", "payments").
If not provided, review the entire API surface.

============================================================
PHASE 1: STACK DETECTION & API DISCOVERY
============================================================

1. Identify the tech stack:
   - Read package.json, pubspec.yaml, requirements.txt, go.mod, Cargo.toml, Gemfile, pom.xml.
   - Identify the API framework (Express, Fastify, Hono, Flask, Django REST, Spring, Rails, Gin, Actix, etc.).
   - Identify middleware chain (auth, validation, rate limiting, CORS, logging).

2. Discover all endpoints:
   - Scan route definitions (app.get, router.post, @app.route, @GetMapping, etc.).
   - Scan OpenAPI/Swagger specs if they exist.
   - Scan GraphQL schema definitions if applicable.
   - For each endpoint, record: method, path, handler function, middleware chain, auth requirement.

3. Build the endpoint inventory:

   | Method | Path | Handler | Auth | Middleware | Request Type | Response Type |
   |--------|------|---------|------|------------|-------------|---------------|

============================================================
PHASE 2: NAMING CONVENTION REVIEW
============================================================

REST RESOURCE NAMING:
- Resources MUST be plural nouns: `/users`, `/orders`, `/products`.
- Flag singular nouns: `/user`, `/order` (should be `/users`, `/orders`).
- Flag verbs in paths: `/getUsers`, `/createOrder`, `/deleteProduct`.
  Actions should use HTTP methods, not URL verbs.
- Flag inconsistent pluralization: `/users` in one place, `/user` in another.

NESTING & HIERARCHY:
- Nested resources should express ownership: `/users/:id/orders`.
- Flag deep nesting (> 3 levels): `/users/:id/orders/:id/items/:id/reviews`.
  Recommend flattening with query parameters or top-level resources.
- Flag inconsistent nesting: `/users/:id/orders` exists but `/orders/:id` also exists
  without the user context.

PATH CONVENTIONS:
- Flag mixed casing: `/userProfiles` vs `/user-profiles`.
- Verify consistent case convention (kebab-case recommended for URLs).
- Flag file extensions in paths: `/users.json` (use Accept header instead).
- Flag trailing slashes inconsistency: some paths with `/`, some without.

QUERY PARAMETER CONVENTIONS:
- Filtering: consistent naming (e.g., `filter[status]=active` or `status=active`).
- Sorting: consistent convention (e.g., `sort=name` or `sort=-created_at`).
- Field selection: consistent convention (e.g., `fields=name,email`).
- Flag ad-hoc query parameter naming that differs across endpoints.

============================================================
PHASE 3: HTTP METHOD SEMANTICS
============================================================

For each endpoint, verify correct HTTP method usage:

GET:
- Must be safe (no side effects) and idempotent.
- Flag GET requests that modify data (create, update, delete).
- Flag GET requests with request bodies (some clients don't support this).

POST:
- Used for creation or actions that aren't idempotent.
- Should return 201 with Location header for resource creation.
- Flag POST used for retrieval (should be GET).

PUT:
- Used for full resource replacement. Must be idempotent.
- Flag PUT used for partial updates (should be PATCH).
- Flag PUT that creates new resources without consistent behavior.

PATCH:
- Used for partial resource updates.
- Should accept only the fields being changed, not the full resource.
- Flag PATCH that requires all fields (should be PUT).

DELETE:
- Must be idempotent (deleting twice = same result).
- Flag DELETE with request body (non-standard, though some APIs use it).
- Verify soft-delete vs hard-delete consistency.

============================================================
PHASE 4: STATUS CODE REVIEW
============================================================

Verify correct HTTP status codes for each endpoint:

SUCCESS CODES:
- 200 OK: GET, PUT, PATCH responses with body.
- 201 Created: POST that creates a resource (must include Location header).
- 204 No Content: DELETE, PUT, PATCH with no response body.
- Flag 200 returned for creation (should be 201).
- Flag 200 with empty body (should be 204).

CLIENT ERROR CODES:
- 400 Bad Request: Malformed request syntax, invalid parameters.
- 401 Unauthorized: Missing or invalid authentication.
- 403 Forbidden: Authenticated but not authorized.
- 404 Not Found: Resource doesn't exist.
- 409 Conflict: Resource state conflict (duplicate, version mismatch).
- 422 Unprocessable Entity: Valid syntax but semantic errors (validation failures).
- 429 Too Many Requests: Rate limit exceeded.
- Flag 401 used for authorization failures (should be 403).
- Flag 400 used for all errors (should differentiate 400/401/403/404/409/422).
- Flag 500 returned for client errors (input validation should be 4xx).

SERVER ERROR CODES:
- 500 Internal Server Error: Unexpected server failure.
- 502/503/504 for proxy/gateway/timeout scenarios.
- Flag 200 returned when an error occurred (masking failures).

============================================================
PHASE 5: PAGINATION, FILTERING & SORTING
============================================================

PAGINATION:
- Flag list endpoints without pagination (unbounded results).
- Check pagination style consistency across all list endpoints:
  - Cursor-based: `cursor`, `after`, `before` (recommended for real-time data).
  - Offset-based: `page`, `limit`, `offset` (acceptable for static data).
- Verify response includes: items, total count (or has_more), next/previous links.
- Flag inconsistent pagination parameters across endpoints.
- Check default and maximum page sizes (unbounded page_size = DoS vector).

FILTERING:
- Verify consistent filtering syntax across all endpoints.
- Flag endpoints that accept filter parameters but don't validate them.
- Flag filter parameters that allow expensive operations (regex on unindexed fields).

SORTING:
- Verify consistent sort parameter format (e.g., `sort=field` / `sort=-field` for desc).
- Flag sort parameters on unindexed fields (performance risk).

============================================================
PHASE 6: ERROR RESPONSE FORMAT
============================================================

Check error response consistency across all endpoints:

RECOMMENDED FORMAT:
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [{ "field": "email", "issue": "Invalid format" }]
  }
}
```

CHECK:
- Is there a consistent error response schema?
- Do all endpoints use the same error format?
- Are error codes machine-readable (not just HTTP status codes)?
- Are error messages human-readable and helpful?
- Flag raw exception messages leaked to clients.
- Flag inconsistent error shapes (some return `{ error }`, others `{ message }`, others `{ errors }`).
- Do validation errors include field-level detail?

============================================================
PHASE 7: ADVANCED API PATTERNS
============================================================

VERSIONING:
- Is API versioning in use? Check for: URL path (`/v1/`), header (`Accept-Version`),
  query param (`?version=1`), or no versioning.
- Is the versioning strategy consistent across all endpoints?
- Flag mixed versioning strategies.
- If no versioning, flag as recommendation for any public API.

RATE LIMITING:
- Are rate limiting headers present? (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`).
- Is rate limiting enforced consistently across endpoints?
- Are rate limits documented?
- Flag endpoints without rate limiting that could be abused (login, search, export).

IDEMPOTENCY:
- For POST/PATCH endpoints that create or modify resources:
  - Is there an idempotency key mechanism (`Idempotency-Key` header)?
  - Can duplicate requests cause duplicate resources?
  - Flag mutation endpoints without idempotency protection.

HATEOAS / LINKS:
- Do responses include navigational links (self, next, prev, related resources)?
- Is the link format consistent (HAL, JSON:API, custom)?
- Flag if the API claims RESTful but has no hypermedia controls (Level 2 vs Level 3 REST).

CONTENT NEGOTIATION:
- Is the Accept header respected?
- Are Content-Type headers set correctly on responses?
- Flag responses that return JSON without `application/json` Content-Type.


============================================================
SELF-HEALING VALIDATION (max 2 iterations)
============================================================

After producing the review, validate completeness and consistency:

1. Verify all required output sections are present and non-empty.
2. Verify every finding references a specific file or code location.
3. Verify recommendations are actionable (not vague).
4. Verify severity ratings are justified by evidence.

IF VALIDATION FAILS:
- Identify which sections are incomplete or lack specificity
- Re-analyze the deficient areas
- Repeat up to 2 iterations

============================================================
OUTPUT
============================================================

## API Review Report

### Stack: {detected stack}
### Scope: {what was reviewed}
### Endpoints Reviewed: {count}

### API Maturity Level: {Richardson Level 0/1/2/3}

### Findings Summary

| Category | Issues | Severity Breakdown |
|---|---|---|
| Naming Conventions | {n} | {Critical: n, High: n, Medium: n, Low: n} |
| HTTP Semantics | {n} | ... |
| Status Codes | {n} | ... |
| Pagination/Filtering | {n} | ... |
| Error Format | {n} | ... |
| Versioning | {n} | ... |
| Rate Limiting | {n} | ... |
| Idempotency | {n} | ... |

### Detailed Findings

1. **{API-001}: {title}** -- Severity: {Critical/High/Medium/Low}
   - Endpoint: `{METHOD} {path}`
   - Location: `{file:line}`
   - Issue: {description}
   - Recommendation: {specific fix}

### Endpoint Inventory

| Method | Path | Auth | Pagination | Status Codes Used | Error Format | Issues |
|---|---|---|---|---|---|---|
| {GET} | {/users} | {JWT} | {cursor} | {200,404} | {consistent} | {0} |

### Consistency Score: {score}/100

### Top Recommendations (ranked by impact)
1. {recommendation} -- affects {N} endpoints
2. ...

DO NOT:
- Flag internal/private APIs for HATEOAS compliance (it's optional for internal APIs).
- Require versioning on APIs with a single consumer.
- Flag GraphQL APIs for REST naming violations (different paradigm).
- Recommend changes that would break existing API consumers without a migration plan.
- Flag health check or metrics endpoints for missing auth (they're typically public).

NEXT STEPS:
- "Run `/api-surface` to generate a complete API inventory and dependency graph."
- "Run `/security-review` to check for auth and injection vulnerabilities."
- "Run `/iterate` to implement the recommended fixes."
- "Run `/api-docs` to generate or update API documentation."


============================================================
SELF-EVOLUTION TELEMETRY
============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:
- Look for the project path in `~/.claude/projects/`
- If found, append to `skill-telemetry.md` in that memory directory

Entry format:
```
### /api-review — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}
```

Only log if the memory directory exists. Skip silently if not found.
Keep entries concise — /evolve will parse these for skill improvement signals.

