api-review

API Review Skill

Setup

Before starting: check .handoff/sessions/ for active sessions, read context status.yaml, run git status. Follow .rules/universal.md (Plan -> Approve -> Execute).

You are reviewing API design for consistency, correctness, and adherence to REST best practices. APIs are contracts — once published, they're hard to change.

Process

Step 1: Discover Endpoints

1. Find route files — Look for:
   • Laravel: routes/api.php, routes/web.php
   • Express/Fastify: routes/, src/routes/
   • Next.js: app/api/, pages/api/
2. List all endpoints — Method, path, controller, middleware
3. Check for API versioning — /api/v1/, /api/v2/ patterns

Step 2: Review Naming Conventions

Check every endpoint against these rules:

• Nouns, not verbs — /users not /getUsers
• Plural resources — /users not /user
• Kebab-case for multi-word — /user-preferences not /userPreferences
• Nested resources for relationships — /users/{id}/orders not /user-orders
• Consistent ID parameter naming — {id} or {userId} but not mixed
• No trailing slashes — /users not /users/
• No file extensions — /users not /users.json

Step 3: Review HTTP Methods

• GET — Read only, no side effects, cacheable
• POST — Create new resource, returns 201 + Location header
• PUT — Full update (replace), idempotent
• PATCH — Partial update, only changed fields
• DELETE — Remove resource, returns 204 or 200

Common mistakes:

• POST for updates (should be PUT/PATCH)
• GET with side effects (should be POST)
• DELETE that returns the deleted resource without the client needing it

Step 4: Review Response Format

Check for consistent response structure:

// Success (single resource)
{
  "data": { "id": "...", "type": "user", ... }
}

// Success (collection)
{
  "data": [...],
  "meta": { "total": 100, "page": 1, "per_page": 20 }
}

// Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable message",
    "details": [{ "field": "email", "message": "Required" }]
  }
}