api-review— agent skill

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).

1. 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.

1. Build the endpoint inventory:

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

{
  "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

Detailed Findings

1. {API-001}: {title} -- Severity: {Critical/High/Medium/Low}

• Endpoint: {METHOD} {path}
• Location: {file:line}
• Issue: {description}
• Recommendation: {specific fix}

Endpoint Inventory

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.