api-design-reviewer

name	api-design-reviewer
description	REST API design review and best practices. Naming conventions, HTTP methods, pagination, error formats, versioning, breaking change detection, rate limiting, HATEOAS. Use when designing or reviewing APIs.

API Design Reviewer

Comprehensive API design analysis for REST conventions, consistency, and industry standards.

---

REST Design Principles

Resource Naming

✅ Good:                          ❌ Bad:
/api/v1/users                     /api/v1/getUsers
/api/v1/user-profiles             /api/v1/user_profiles
/api/v1/orders/123/line-items     /api/v1/orders/123/lineItems

Rules: Plural nouns for collections. Kebab-case for multi-word resources. CamelCase for JSON fields. Use HTTP methods instead of verbs in URLs.

HTTP Methods

Method	Purpose	Idempotent	Safe
GET	Retrieve resources	Yes	Yes
POST	Create new resources	No	No
PUT	Replace entire resource	Yes	No
PATCH	Partial update	No	No
DELETE	Remove resource	Yes	No

URL Structure

Collection:   /api/v1/users
Individual:   /api/v1/users/123
Nested:       /api/v1/users/123/orders
Action:       /api/v1/users/123/activate (POST)
Filtering:    /api/v1/users?status=active&role=admin

---

Pagination Patterns

Cursor-Based (Recommended)

{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTIzfQ==",
    "hasMore": true
  }
}

Implementation tip: fetch LIMIT + 1 rows to determine hasMore without a separate count query.

Offset-Based

{
  "data": [...],
  "pagination": { "offset": 20, "limit": 10, "total": 150, "hasMore": true }
}

When to Use Which

Use Case	Pagination Type	Why
Admin dashboards, small datasets (<10K)	Offset	Users expect page numbers
Infinite scroll, feeds, large datasets	Cursor	Consistent performance at any depth
Public APIs	Cursor (default), offset (optional)	Scalable by default
Search results	Offset	Users expect "page N of M"

---

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters",
    "details": [
      { "field": "email", "code": "INVALID_FORMAT", "message": "Email address is not valid" }
    ],
    "requestId": "req-123456",
    "timestamp": "2024-02-16T13:00:00Z"
  }
}

Status Code Usage

Code	Meaning
200	Success (GET, PUT, PATCH)
201	Created (POST)
204	No Content (DELETE)
400	Validation error
401	Authentication required
403	Permission denied
404	Resource not found
409	Conflict (duplicate, version mismatch)
422	Semantic errors (valid syntax, bad logic)
429	Rate limit exceeded
500	Internal server error

---

Versioning Strategies

Strategy	Example	Pros	Cons
URL (recommended)	/api/v1/users	Clear, easy to route	URL proliferation
Header	Accept: application/vnd.api+json;version=1	Clean URLs	Less visible
Query parameter	/api/users?version=1	Simple	Not RESTful

Versioning Lifecycle

1. Start with /api/v1/ — version only when breaking changes arise
2. Maintain at most 2 active versions (current + previous)
3. Deprecation timeline (public APIs):
   - Announce deprecation with 6 months notice
   - Add Sunset header: Sunset: Sat, 01 Jan 2026 00:00:00 GMT
   - Return 410 Gone after sunset date

---

Breaking vs Non-Breaking Changes

Safe (Non-Breaking)

• Adding optional request fields
• Adding response fields
• Adding new endpoints
• Making required fields optional

Breaking (Require Version Bump)

• Removing response fields
• Making optional fields required
• Changing field types
• Removing or renaming endpoints
• Changing URL structure

---

Rate Limiting

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

429 Response

{ "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests", "retryAfter": 3600 } }

Rate Limit Tiers

Tier	Limit	Window	Use Case
Anonymous	30/min	Per IP	Public endpoints
Authenticated	100/min	Per user	Standard API access
Premium	1000/min	Per API key	Paid API plans
Internal	10000/min	Per service	Service-to-service

---

Filtering, Sorting, and Search

# Equality filters
GET /api/v1/orders?status=active&customer_id=abc-123

# Comparison operators (bracket notation)
GET /api/v1/products?price[gte]=10&price[lte]=100

# Multiple values (comma-separated)
GET /api/v1/products?category=electronics,clothing

# Sorting (prefix - for descending, comma for multi-field)
GET /api/v1/products?sort=-created_at,price

# Full-text search
GET /api/v1/products?q=wireless+headphones

# Sparse fieldsets (reduce payload)
GET /api/v1/users?fields=id,name,email

---

Authentication Patterns

Pattern	Header	Use Case
Bearer Token	Authorization: Bearer <token>	JWT, OAuth 2.0
API Key	X-API-Key: <key>	Service-to-service
Basic Auth	Authorization: Basic <base64>	Simple auth (with HTTPS)

---

Idempotency

For non-idempotent operations (POST), use idempotency keys:

POST /api/v1/payments
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

---

Review Checklist

• Resources use plural nouns, kebab-case
• Correct HTTP methods for each operation
• Consistent error response format
• Pagination on all list endpoints
• Versioning strategy defined
• Rate limiting headers present
• Authentication documented
• Breaking changes flagged

---

Anti-Patterns

Anti-Pattern	Fix
Verb-based URLs (/getUsers)	Use nouns + HTTP methods
Inconsistent response shapes	Standardize envelope format
Deep nesting (/a/1/b/2/c/3/d)	Limit to 2 levels; use query params
Ignoring status codes	Use specific codes per error type
Missing pagination	Always paginate lists
No versioning	Plan for API evolution from day one
Exposing internal structure	Design for external consumption