api-designer

Purpose

Design or review REST API surfaces — routes, resource modeling, request/response shapes, status codes, versioning, and error formats — so the API is consistent, predictable, and follows established conventions rather than ad hoc choices per endpoint.

When to Use

• Designing new endpoints or a new API from scratch.
• Reviewing an existing API for consistency before it gets more consumers.
• The user has a rough idea of what an endpoint should do and needs it shaped into a proper REST contract.

What to Analyze / Do

1. Resource modeling — identify the actual resources and their relationships; prefer nouns-as-resources over RPC-style action endpoints where REST conventions fit naturally.
2. Route design — consistent pluralization, nesting depth (avoid over-nesting past 2 levels), and clear path parameters.
3. HTTP methods & status codes — correct verb per operation (GET/POST/PUT/PATCH/DELETE), and status codes that mean what they say (200 vs 201 vs 204, 400 vs 422, 404 vs 403).
4. Request/response shape — consistent envelope (or deliberately no envelope) across endpoints, consistent field naming (camelCase vs snake_case — pick one and stay consistent with the rest of the API).
5. Validation & errors — what's validated, what error shape is returned, whether error responses are consistent and machine-parseable.
6. Pagination, filtering, sorting — for any list endpoint, define these explicitly rather than leaving them unbounded.
7. Versioning & backward compatibility — how breaking changes are handled without breaking existing consumers.

Output Format

• For new design: proposed routes as a table (Method, Path, Description), then example request/response JSON per endpoint, then validation/error notes.
• For review: findings grouped by inconsistency type (naming, status codes, pagination, etc.), each with the specific endpoints affected and the recommended fix.

Avoid

• Proposing a fully RPC-style API when the resources genuinely fit REST conventions (or vice versa — forcing REST onto an inherently action-based operation).
• Inventing a new convention when the existing API already has an established one — match it unless explicitly asked to redesign.
• Ignoring auth/permissions implications of a new route (who can call it) even if full auth design is out of scope.