API Design Guidelines for Modern Applications

APIs are contracts between systems. Good design makes them intuitive to use and easy to maintain. Here are guidelines for designing APIs that stand the test of time.

Consistency Is Key#

// Consistent naming across endpoints
// ✓ Good - predictable patterns
GET  /users
GET  /users/:id
POST /users
GET  /orders
GET  /orders/:id
POST /orders

// ✗ Bad - inconsistent patterns
GET  /users
GET  /user/:id
POST /createUser
GET  /order-list
GET  /orders/:orderId

// Consistent response format
interface ApiResponse<T> {
  data: T;
  meta?: {
    pagination?: PaginationMeta;
    requestId: string;
    timestamp: string;
  };
}

interface ErrorResponse {
  error: {
    code: string;
    message: string;
    details?: any;
  };
  meta: {
    requestId: string;
    timestamp: string;
  };
}

Predictable Behavior#

// Status codes should be predictable
// 2xx - Success
201 // Created - POST success, include Location header
200 // OK - GET, PUT, PATCH success
204 // No Content - DELETE success

// 4xx - Client errors
400 // Bad Request - Malformed request
401 // Unauthorized - No/invalid authentication
403 // Forbidden - Authenticated but not allowed
404 // Not Found - Resource doesn't exist
409 // Conflict - Resource state conflict
422 // Unprocessable - Validation failed

// 5xx - Server errors
500 // Internal Error - Unexpected failure
503 // Service Unavailable - Temporary

// Idempotency
// GET, PUT, DELETE should be idempotent
PUT /users/123 { name: "New Name" }
// Same result no matter how many times called

// POST is not idempotent - use idempotency keys
POST /orders
Idempotency-Key: unique-request-id

Resource Design#

// Resources are nouns, not verbs
// ✓ Good
POST /orders          // Create order
POST /orders/123/ship // Ship order (action as sub-resource)

// ✗ Bad
POST /createOrder
POST /shipOrder/123

// Relationships
GET /users/123/orders          // User's orders
GET /orders?userId=123         // Also valid
GET /orders/456/items          // Order's items

// Keep nesting shallow (max 2 levels)
// ✓ Good
GET /orders/456/items

// ✗ Too deep
GET /users/123/orders/456/items/789/details

// Actions as sub-resources
POST /orders/123/cancel
POST /users/123/verify-email
POST /payments/456/refund

Filtering and Pagination#

// Filtering
GET /products?category=electronics
GET /products?category=electronics&brand=apple
GET /products?price[gte]=100&price[lte]=500
GET /products?status=active,pending  // Multiple values

// Sorting
GET /products?sort=price           // Ascending
GET /products?sort=-price          // Descending
GET /products?sort=-createdAt,name // Multiple fields

// Pagination - Cursor-based (preferred)
GET /users?limit=20
GET /users?limit=20&cursor=eyJpZCI6MTAwfQ

Response:
{
  "data": [...],
  "meta": {
    "pagination": {
      "limit": 20,
      "hasMore": true,
      "nextCursor": "eyJpZCI6MTIwfQ"
    }
  }
}

// Pagination - Offset-based
GET /users?limit=20&offset=40

Response:
{
  "data": [...],
  "meta": {
    "pagination": {
      "total": 500,
      "limit": 20,
      "offset": 40,
      "hasMore": true
    }
  }
}

Field Selection#

// Sparse fieldsets
GET /users/123?fields=id,name,email

// Expand related resources
GET /orders/123?include=customer,items
GET /orders/123?expand=customer

// Response
{
  "data": {
    "id": "123",
    "total": 99.99,
    "customer": {
      "id": "456",
      "name": "John Doe"
    },
    "items": [
      { "id": "789", "name": "Widget", "quantity": 2 }
    ]
  }
}

Error Responses#

// Always include:
// - Error code (machine-readable)
// - Message (human-readable)
// - Request ID (for debugging)

// Validation error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Invalid email format" },
      { "field": "password", "message": "Must be at least 8 characters" }
    ]
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

// Resource not found
{
  "error": {
    "code": "NOT_FOUND",
    "message": "User with ID 999 not found"
  },
  "meta": {
    "requestId": "req_def456"
  }
}

// Rate limit
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "details": {
      "retryAfter": 30
    }
  }
}

Backwards Compatibility#

// Adding fields is safe
// v1: { id, name }
// v2: { id, name, email }  // OK - additive

// Removing/renaming fields breaks clients
// Use deprecation warnings first
response.setHeader('Deprecation', 'true');
response.setHeader('Sunset', 'Sat, 01 Jun 2025 00:00:00 GMT');

// Version your API
/v1/users
/v2/users

// Or use headers
Accept: application/vnd.api+json; version=2

// Changelog
## v2.0 (2024-01-15)
- Added `email` field to User
- Deprecated `fullName`, use `firstName` + `lastName`
- Changed pagination from offset to cursor-based

Documentation#

# OpenAPI spec
openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
  description: |
    ## Authentication
    All endpoints require Bearer token.

    ## Rate Limits
    - Standard: 100 requests/minute
    - Authenticated: 1000 requests/minute

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                data:
                  - id: "123"
                    name: "John"

Best Practices Summary#

Consistency:
✓ Uniform naming conventions
✓ Predictable response format
✓ Consistent error handling
✓ Standard HTTP methods

Design:
✓ Resource-oriented URLs
✓ Shallow nesting
✓ Proper status codes
✓ Idempotent operations

Usability:
✓ Clear documentation
✓ Helpful error messages
✓ Request IDs for debugging
✓ Rate limit headers

Evolution:
✓ Version from the start
✓ Deprecate before removing
✓ Changelog maintenance
✓ Sunset headers

Good API design requires consistency, predictability, and clear documentation. Make APIs intuitive by following REST conventions, provide helpful errors, and plan for evolution. Your API is a product—treat it with the same care as your user interface.