API Design Review

The Problem

Bad API design creates permanent technical debt. Once clients integrate with your endpoints, changing the contract breaks their code. Inconsistent naming (some endpoints use camelCase, others snake_case), missing pagination on list endpoints, unclear error responses, and no versioning strategy all compound into an API that nobody wants to consume and nobody can safely evolve.

The Prompt

Review the following API design. Act as a senior API architect evaluating for consistency, scalability, and developer experience.

API TYPE: [REST / GraphQL / gRPC]
CONSUMERS: [e.g., mobile app, third-party developers, internal frontend]
SPEC/CODE:
[paste route definitions, OpenAPI spec, or controller code]

Evaluate across these dimensions:

1. **Resource Design**
   - Are resources named as nouns (not verbs)? Plural or singular consistently?
   - Are nested resources correctly scoped (/users/:id/orders, not /getUserOrders)?
   - Is the resource hierarchy shallow (max 2-3 levels deep)?

2. **HTTP Semantics**
   - Are HTTP methods used correctly (GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes)?
   - Do GET requests have side effects?
   - Are status codes accurate (201 for creation, 204 for no content, 404 vs 400)?

3. **Pagination & Filtering**
   - Do list endpoints support pagination (cursor-based preferred over offset)?
   - Is the total count / next page indicator included?
   - Are filters, sorting, and field selection supported consistently?

4. **Error Responses**
   - Is the error format consistent across all endpoints?
   - Do errors include: status code, error type, human message, and machine-readable code?
   - Are validation errors itemized per field?

5. **Versioning**
   - Is there a versioning strategy (URL path, header, query param)?
   - Are breaking changes documented? Is deprecation communicated?

6. **Security**
   - Is authentication required on all non-public endpoints?
   - Are rate limits documented?
   - Is sensitive data excluded from responses by default?

7. **Developer Experience**
   - Are response shapes predictable (same wrapper for all endpoints)?
   - Is the API self-documenting (OpenAPI/Swagger)?
   - Are request/response examples provided?

For each issue, provide:
- **Endpoint**: The affected route
- **Severity**: breaking (will hurt consumers) / inconsistent / improvement
- **Problem**: What violates API design best practices
- **Fix**: Corrected endpoint design with example request/response

Example Output

## API Design Review: 6 issues found

### Breaking: Inconsistent Error Format
Endpoints return different error shapes:
  POST /users → { "error": "Email taken" }
  GET /orders → { "message": "Not found", "code": 404 }
Fix: Standardize all errors:
  {
    "status": 404,
    "error": "NOT_FOUND",
    "message": "Order with ID 123 not found",
    "details": []
  }

### Breaking: Unbounded List Endpoint
GET /api/products returns ALL products with no pagination.
Fix: Default to cursor-based pagination:
  GET /api/products?limit=20&cursor=abc123
  Response: { "data": [...], "pagination": { "next_cursor": "def456", "has_more": true } }

### Inconsistent: Mixed Naming Conventions
  GET /api/userProfiles (camelCase)
  GET /api/order_items (snake_case)
Fix: Choose one convention (kebab-case recommended for URLs):
  GET /api/user-profiles
  GET /api/order-items

When to Use

Run this before publishing an API to external consumers, during design reviews for new endpoints, or when auditing an existing API for consistency. Most valuable early in the design phase — fixing API inconsistencies after clients are integrated is ten times harder than getting it right upfront.

Pro Tips

• Include all endpoints — API design issues are often about consistency across the surface, not within a single endpoint. Provide the full route list.
• Specify your consumers — mobile clients need different pagination than web dashboards. Third-party developers need different error detail than internal teams.
• Ask for an OpenAPI spec — follow up with “Generate an OpenAPI 3.0 spec for the corrected API design” to get a machine-readable contract.
• Version from day one — even if you think you will not need versioning, adding /v1/ costs nothing now and saves massive migration pain later.