REST API Design: The Decisions That Come Back to Haunt You

API design decisions seem abstract until you're explaining to ten client teams why the /user endpoint inconsistently returns snake_case sometimes and camelCase other times. Here are the choices that feel small and aren't.

URL Structure: Rules Worth Following

• Resources are nouns, never verbs: /users, /orders, /products — not /getUsers, /createOrder. The HTTP method (GET, POST, PUT, DELETE) is the verb.
• Hierarchical relationships in the path: /users/123/orders returns orders for user 123. Don't go deeper than 3 levels — /users/123/orders/456/items is the maximum reasonable nesting.
• Lowercase, hyphen-separated: /payment-methods not /PaymentMethods or /payment_methods. Uppercase in URLs is technically valid but a persistent source of confusion.
• Filters and search go in query params: GET /users?status=active&role=admin not GET /users/active/admin.

The Error Response Format Matters More Than Most APIs Treat It

Every API invents its own error format. The result: every client has to parse differently. Consider RFC 7807 (Problem Details for HTTP APIs) — a standard format that's gaining adoption:

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The email field is required",
  "errors": [
    {"field": "email", "message": "Required"}
  ]
}

Authentication: Don't Invent Your Own

API key in Authorization header (Authorization: Bearer API_KEY) for simple cases. OAuth 2.0 for anything involving user permission delegation. JWT for stateless user authentication. The temptation to invent a custom auth scheme is real and almost always wrong — established patterns have known security properties; custom schemes have unknown ones.

The Versioning Decision Tree

Public API with external consumers: version from day one in the URL (/v1/). Internal API where you control all consumers: you can avoid versioning if you deploy clients and server together. Start adding versioning as soon as you have any external consumer or can't coordinate deploys. The cost of adding versioning later is high; the cost of including it from the start is low.

Rate Limiting: Document It, Communicate It

Return rate limit info in response headers, not just 429 errors: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Clients need this to implement backoff correctly. Include Retry-After on 429 responses. Rate limits that exist but aren't documented cause production incidents when clients hit them unexpectedly.