API Design Reviewer

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

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

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

Versioning Strategies

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

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

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