REST API Design Best Practices for Modern Web Applications

A well-designed API is the backbone of modern web applications. Here are the best practices that make APIs a pleasure to work with.

URL Design

Use Nouns, Not Verbs

• Good: GET /users, POST /orders
• Bad: GET /getUsers, POST /createOrder

Use Plural Nouns

• Good: /users, /products, /orders
• Bad: /user, /product, /order

Nest for Relationships

• GET /users/123/orders — orders belonging to user 123
• GET /orders/456/items — items in order 456

Keep It Flat

Don't nest more than two levels. Use query parameters for filtering instead.

HTTP Methods

| Method | Purpose | Example | |--------|---------|---------| | GET | Retrieve data | GET /users | | POST | Create new resource | POST /users | | PUT | Replace entire resource | PUT /users/123 | | PATCH | Update partial resource | PATCH /users/123 | | DELETE | Remove resource | DELETE /users/123 |

Response Codes

Success

• 200: OK (general success)
• 201: Created (resource successfully created)
• 204: No Content (success with no response body)

Client Errors

• 400: Bad Request (invalid input)
• 401: Unauthorized (not authenticated)
• 403: Forbidden (not authorized)
• 404: Not Found
• 422: Unprocessable Entity (validation error)
• 429: Too Many Requests (rate limited)

Server Errors

• 500: Internal Server Error
• 503: Service Unavailable

Error Handling

Return consistent error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email format"
      }
    ]
  }
}

Authentication

API Keys

Simple but limited. Good for server-to-server communication. Pass in headers, never in URLs.

JWT (JSON Web Tokens)

Stateless authentication. Good for user-facing APIs. Include in Authorization header: Bearer <token>

OAuth 2.0

Industry standard for third-party authorization. More complex but provides delegated access and scoping.

Pagination

For list endpoints, always paginate:

GET /users?page=2&limit=20

Response:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Filtering and Sorting

GET /products?category=electronics&min_price=100&sort=-created_at

Use query parameters for filtering. Prefix sort fields with - for descending order.

Versioning

Include the version in the URL:

/api/v1/users
/api/v2/users

Never break existing versions. Add new versions when making breaking changes.

Rate Limiting

Protect your API from abuse:

• Set reasonable rate limits per API key
• Return 429 status when exceeded
• Include rate limit headers in responses

Documentation

Good API documentation includes:

• Authentication setup
• Endpoint descriptions with examples
• Request and response schemas
• Error code reference
• Rate limiting details
• Changelog

Use tools like Swagger/OpenAPI for interactive documentation.

A well-designed API saves countless hours for everyone who uses it.