api-design-reviewer

---
name: api-design-reviewer
description: Use when reviewing a PR that adds or changes API endpoints, auditing an existing REST API before a v2 migration, or establishing shared API design standards for a team.
category: Engineering
version: 1.0.0
tools: []
---

# API Design Reviewer

Review REST API designs for convention violations, breaking changes, and overall design quality, and hand back a structured scorecard. Applies to PRs adding/changing endpoints, v2-migration audits, and establishing team-wide API standards.

## Review Method

Work through three passes and report findings for each before signing off — never approve an API design on prose alone; always cite the specific endpoint, field, or status code.

1. **Convention lint pass** — walk the endpoint list (or OpenAPI/Swagger spec) checking: resource naming (kebab-case for resources, camelCase for fields), correct HTTP method usage, RESTful URL structure, appropriate status codes, consistent error response shapes, and documentation coverage (missing descriptions/examples).
2. **Breaking-change pass** — when reviewing a spec revision, diff old vs. new: removed or deprecated endpoints, changed response shapes, removed/renamed fields, field type changes, newly required fields, and changed expected status codes. Any of these require a version bump or an explicit migration note; flag them as blocking until addressed.
3. **Scorecard pass** — score the design across five weighted dimensions and assign a letter grade (A–F): Consistency (30%, naming/response/structural patterns), Documentation Quality (20%), Security Implementation (20%, auth/authz/security headers), Usability Design (15%, discoverability/DX), Performance Patterns (15%, caching/pagination/efficiency). Agree a minimum acceptable grade with the team (commonly B) and treat anything below it as needing rework before merge.

## Core Capabilities

- **Linting/convention analysis**: naming, HTTP method correctness, URL consistency, status-code compliance, error-format consistency, documentation gaps.
- **Breaking-change detection**: endpoint removal, response-shape changes, field removal/rename, type changes, new required fields, status-code changes, with severity/impact assessment.
- **Design scoring**: the 5-dimension rubric above, with a letter grade and concrete improvement recommendations.

## REST Design Principles

**Resource naming** — good: `/api/v1/users`, `/api/v1/user-profiles`, `/api/v1/orders/123/line-items`. Bad: `/api/v1/getUsers` (verb-based), `/api/v1/user_profiles` (snake_case), `/api/v1/orders/123/lineItems` (inconsistent casing).

**HTTP methods**: GET (retrieve, safe + idempotent), POST (create, not idempotent), PUT (replace entire resource, idempotent), PATCH (partial update, not necessarily idempotent), DELETE (remove, idempotent).

**URL structure**: collections (`/api/v1/users`), individual resources (`/api/v1/users/123`), nested resources (`/api/v1/users/123/orders`), actions as POST sub-paths (`/api/v1/users/123/activate`), filtering via query params (`/api/v1/users?status=active&role=admin`).

## Versioning Strategies

1. **URL versioning** (recommended) — `/api/v1/users` → `/api/v2/users`. Pros: explicit, easy to route. Cons: URL proliferation, caching complexity.
2. **Header versioning** — `Accept: application/vnd.api+json;version=1`. Pros: clean URLs, content negotiation. Cons: less visible, harder to test manually.
3. **Media-type versioning** — `Accept: application/vnd.myapi.v1+json`. Pros: RESTful, supports multiple representations. Cons: complex to implement.
4. **Query-parameter versioning** — `/api/users?version=1`. Pros: simple. Cons: not RESTful, easily ignored.

## Pagination Patterns

- **Offset-based**: `{ "pagination": { "offset": 20, "limit": 10, "total": 150, "hasMore": true } }`
- **Cursor-based**: `{ "pagination": { "nextCursor": "eyJpZCI6MTIzfQ==", "hasMore": true } }`
- **Page-based**: `{ "pagination": { "page": 3, "pageSize": 10, "totalPages": 15, "totalItems": 150 } }`

Every list endpoint should implement one of these — missing pagination on a collection endpoint is a common defect to flag.

## Error Response Formats

Standard shape: `{ "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [{ "field": "email", "code": "INVALID_FORMAT", "message": "..." }], "requestId": "req-123456", "timestamp": "2026-02-16T13:00:00Z" } }`.

HTTP status codes to check for correct usage: **400** Bad Request (invalid syntax/params), **401** Unauthorized (auth required), **403** Forbidden (authenticated but not authorized), **404** Not Found, **409** Conflict (duplicate/version mismatch), **422** Unprocessable Entity (valid syntax, semantic error), **429** Too Many Requests (rate limit), **500** Internal Server Error.

## Authentication and Authorization Patterns

- Bearer token: `Authorization: Bearer <token>`
- API key: `X-API-Key: <api-key>` or `Authorization: Api-Key <api-key>`
- OAuth 2.0: `Authorization: Bearer <oauth-access-token>`
- Role-Based Access Control (RBAC): `{ "user": { "id": "123", "roles": ["admin","editor"], "permissions": ["read:users","write:orders"] } }`

## Rate Limiting

Headers: `X-RateLimit-Limit: 1000`, `X-RateLimit-Remaining: 999`, `X-RateLimit-Reset: 1640995200`. On limit exceeded, return 429 with a body like `{ "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests", "retryAfter": 3600 } }`.

## HATEOAS (Hypermedia as the Engine of Application State)

Responses should embed navigable links, e.g. a user resource with `_links: { self, orders, profile, deactivate (POST) }` pointing to related/actionable endpoints — flag APIs that force clients to hardcode URL construction instead.

## Idempotency

GET is always safe/idempotent. PUT and DELETE should be idempotent. PATCH may or may not be. For non-idempotent-by-default operations like payments, require an idempotency key: `POST /api/v1/payments` with header `Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000`.

## Backward Compatibility

**Safe / non-breaking**: adding optional request fields, adding response fields, adding new endpoints, making required fields optional, adding new enum values (with graceful client handling).

**Breaking (requires a version bump)**: removing response fields, making optional fields required, changing field types, removing endpoints, changing URL structures, modifying error response formats.

## OpenAPI/Swagger Coverage

A spec under review should define: API info (title/description/version), server info (base URLs), path definitions for all endpoints/methods, parameter definitions (query/path/header), complete request/response schemas, security definitions, and standard error responses. Best practice: consistent naming, detailed descriptions on all components, examples for complex objects, reusable components/schemas, and full validation against the OpenAPI specification.

## Performance Considerations

- **Caching**: `Cache-Control: public, max-age=3600`, `ETag`, `Last-Modified` — check for conditional-request support.
- **Efficient transfer**: field selection (`?fields=id,name,email`), gzip compression, efficient pagination, ETags for conditional requests.
- **Resource optimization**: avoid N+1 queries, support batch operations, use async processing for heavy operations, support partial updates via PATCH.

## Security Best Practices

- **Input validation**: validate all parameters, sanitize user data, use parameterized queries, enforce request size limits.
- **Authentication security**: HTTPS everywhere, secure token storage, token expiration/refresh, strong authentication mechanisms.
- **Authorization controls**: principle of least privilege, resource-based permissions, fine-grained access control, audit access patterns.

## Best Practices Summary

Consistency first (uniform naming/response/patterns); comprehensive documentation; explicit versioning from day one; consistent error handling; security in every layer; design for scale/efficiency; minimize breaking changes with migration paths; contract testing; observability for usage/performance; prioritize developer experience.

## Common Anti-Patterns to Flag

Verb-based URLs instead of noun resources; inconsistent response formats; over-nested resource hierarchies; wrong/ignored HTTP status codes; vague error messages; missing pagination on list endpoints; no versioning strategy; internal data structures exposed directly instead of a designed external contract; no rate limiting; inadequate testing of error/edge cases.

Regular, disciplined application of the linting, breaking-change, and scorecard passes above keeps API quality improving over time rather than degrading PR by PR.