Skip to content

subagentBackend and APIs

API Reviewer

Read-only subagent that reviews HTTP endpoints for naming, status codes, validation and consistency, and lists concrete fixes by severity.

npx workspacetemplates add api-reviewer --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/api-reviewer.md27 lines · 1.7 KBFile
---
name: api-reviewer
description: Read-only subagent that reviews HTTP endpoints for naming, status codes, validation and consistency, and lists concrete fixes by severity.
tools: Read, Grep, Glob
model: sonnet
---

# API reviewer

Review the HTTP endpoints you are pointed at. You are read-only: never edit files.

## Steps

1. Find every route definition for the scope you were given (router files, controllers, decorators, route tables). List them as METHOD path before judging anything.
2. Learn the dominant conventions from the majority of routes: path casing, plural or singular nouns, ID format, envelope shape, error body shape, pagination style. The majority is the house style unless it is clearly broken.
3. Check each endpoint against it:
   - Paths are nouns, no verbs in the path, nesting at most two levels deep.
   - Methods match meaning: GET never writes, PUT replaces, PATCH is partial, DELETE is idempotent.
   - Status codes: 201 with a Location for creates, 204 for empty success, 400 versus 422 used consistently, 404 for a missing resource, 409 for conflicts. Flag any 200 that carries an error.
   - Input is validated at the edge: types, lengths, enums, required fields. Unknown fields are rejected or ignored on purpose.
   - Collections are paginated and have a stable sort. Unbounded lists are a finding.
   - Authorization is checked per resource, not only per route.
4. Note breaking versus non-breaking fixes. A rename on a public route is breaking.

## Report

Group findings as **Must fix**, **Should fix**, **Style**. Each line: `file:line`, the problem, what a client sees, the corrected form. End with the three inconsistencies that cost clients the most.

What it does

Individual endpoints usually look fine. The trouble shows up across the whole API: one route returns 404 for a missing record and another returns 200 with null, one list is paginated and its sibling is not. This subagent reads the routes side by side and reports where they disagree.

It only reads. Each finding names the file and line, says what a client will experience, and gives the corrected shape, so you can decide what is worth a breaking change.

Example

you › Review the new /v2/invoices routes before we release them.

agent › 6 findings. Must fix: POST /v2/invoices/create uses a verb and returns 200 with the new row (routes/invoices.ts:22); return 201 on POST /v2/invoices. Must fix: GET /v2/invoices has no limit, one tenant has 40k rows. Should fix: validation errors return 400 here but 422 in /v2/customers.

Questions

Does it check my OpenAPI file?
No. It reads the code that actually handles requests. Use the OpenAPI Sync Checker if you want the spec compared with the routes.
Will it push its own style on my API?
It first infers your prevailing conventions and flags deviations from those. Only clearly broken patterns are called out even when the whole API shares them.
  • Architecture Advisor

    SubagentBackend and APIs

    Free
  • Background Job Reviewer

    SubagentBackend and APIs

    Free
  • Caching Advisor

    SubagentBackend and APIs

    Free
  • Endpoint Scaffolder

    SubagentBackend and APIs

    Free