10 Best Practices For REST API Design

1. Design Around Resources, Not Actions

The foundational principle of REST is designing around resources rather than actions. Resources are the nouns of your API--the entities and objects that your system manages. This approach creates intuitive, predictable APIs that developers can navigate without extensive documentation.

Understanding Resources and Collections

A resource is any object important enough to be referenced independently--a user, a product, an order, or a photo. Collections group related resources together, forming the primary organizational structure of your API. For example, in a photo-sharing application, /users represents a collection of users, while /users/username1 identifies a specific user resource.

This resource-oriented approach mirrors how applications naturally model their domain. When developers think about your API, they think about the data they need to access and manipulate, not the underlying operations required. By exposing resources directly, you create mental models that align with real-world concepts.

Use Nouns for URIs, Not Verbs

Your API endpoints should use nouns to represent resources, with HTTP methods defining the operations performed. This separation of concerns makes URLs cleaner and more consistent:

# Bad: Using verbs in URIs
POST /create-user
POST /get-users
POST /update-order
POST /delete-photo

# Good: Nouns with HTTP methods
POST /users # Create a new user
GET /users # Retrieve all users
GET /users/{id} # Retrieve a specific user
PUT /users/{id} # Update a user
DELETE /users/{id} # Delete a user

The verb-based approach introduces redundancy since HTTP methods already define the action. It also leads to inconsistent naming when operations don't map cleanly to standard CRUD actions. By using nouns consistently, you establish predictable patterns that developers can learn once and apply throughout your API.

Keep URIs Hierarchical and Intuitive

Structure your URIs to reflect natural relationships between resources. When one resource belongs to another, that relationship should be evident in the URL structure. For instance, if orders belong to users, the endpoint for accessing a user's orders should be /users/{userId}/orders, not /orders/user/{userId} or some arbitrary identifier.

However, avoid making URI hierarchies too deep. A good rule of thumb is to limit relationships to two levels of nesting (collection/item/collection). Deeper hierarchies become unwieldy and fragile--if relationships change, you may need to restructure your entire API. Instead, use links in responses to navigate to related resources, keeping the core URI structure stable.

2. Master HTTP Methods and Status Codes

HTTP methods and status codes form the vocabulary of your API's communication protocol. Using them correctly ensures that your API behaves consistently with web standards, making it intuitive for developers familiar with HTTP conventions.

The Five Essential HTTP Methods

REST APIs rely on five primary HTTP methods, each with specific semantics that should be respected:

GET retrieves a representation of a resource without modifying it. GET requests are safe and idempotent, meaning they can be repeated without changing the server state. A successful GET returns HTTP 200 with the resource representation, while a missing resource returns 404.

POST creates new resources or submits data for processing. The server typically assigns the new resource's URI and returns it in the Location header. A successful creation returns HTTP 201 (Created) with the new resource or a reference to it. POST can also trigger operations that don't map directly to resource creation, returning 200 or 202 for processing responses.

PUT creates or completely replaces a resource at the specified URI. PUT is idempotent--sending the same request multiple times produces the same result. When updating, PUT requires the complete resource representation in the request body, even if only one field changes.

PATCH performs partial updates, sending only the changed fields rather than the entire resource. This approach reduces bandwidth usage and allows more granular updates. PATCH uses a patch document format (typically JSON Merge Patch or JSON Patch) to specify which fields to modify, add, or remove.

DELETE removes a resource at the specified URI. A successful deletion returns HTTP 204 (No Content), indicating the response body is empty. If the resource doesn't exist, return 404. Implement DELETE as idempotent--repeated deletion attempts on the same resource should return 200 or 204 for the first call and 404 for subsequent calls.

Return Appropriate Status Codes

HTTP status codes communicate the outcome of each request, enabling clients to handle responses correctly without inspecting response bodies:

• 2xx: Success (200 OK, 201 Created, 204 No Content)
• 4xx: Client Error (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity)
• 5xx: Server Error (500 Internal Server Error, 503 Service Unavailable)

Avoid returning generic 200 responses for all success cases--using 201 for creations and 204 for deletions provides semantic clarity. Similarly, don't use 500 for all errors; distinguish between client mistakes (400-499) and server problems (500-599) so clients can adjust their behavior accordingly, as recommended by Swagger's API design best practices.

3. Implement Robust Error Handling

Error responses are your API's way of communicating problems to developers. Well-designed errors accelerate debugging and prevent misuse, while vague errors lead to frustration and support requests.

Create Meaningful Error Payloads

Beyond the HTTP status code, include detailed error information in the response body. A well-structured error response helps developers understand what went wrong and how to fix it:

{
 "error": {
 "code": "VALIDATION_ERROR",
 "message": "The request could not be validated",
 "details": [
 {
 "field": "email",
 "message": "The email field is required"
 },
 {
 "field": "password",
 "message": "Password must be at least 8 characters"
 }
 ],
 "documentation_url": "https://api.example.com/docs/errors/validation"
 }
}

This structure separates the high-level error type (useful for programmatic handling) from specific field-level issues (useful for form validation). Including a documentation URL guides developers toward resolution without requiring them to search for help.

Handle Validation Errors Gracefully

When rejecting requests due to validation failures, return 400 (Bad Request) or 422 (Unprocessable Entity) with specific details about what failed. Use 400 for general client errors and malformed requests, and 422 specifically for semantic validation errors where the syntax is valid but the content fails business rules. Group related errors together, identify the specific fields that failed validation, and provide clear messages that explain both what's wrong and what the correct format should be.

Avoid exposing internal error details that could reveal implementation specifics or security vulnerabilities. While helpful for debugging, stack traces and internal error messages belong in server logs, not API responses.

4. Design for Pagination and Filtering

APIs that return unbounded collections create performance problems and usability issues. Pagination divides large datasets into manageable chunks, while filtering allows clients to request only the data they need.

Implement Cursor-Based or Offset Pagination

Cursor-based pagination uses a marker (typically the ID or timestamp of the last item) to fetch subsequent pages. This approach handles real-time data well since new items added during pagination don't cause duplicates or skipped items:

GET /messages?limit=50&after=msg_4521

Offset pagination uses numeric indices and works well for stable, non-real-time data:

GET /messages?limit=50&offset=100

Include pagination metadata in responses so clients know whether more results exist and can navigate efficiently:

{
 "data": [...],
 "pagination": {
 "total": 1250,
 "limit": 50,
 "offset": 100,
 "has_more": true,
 "next_url": "/messages?limit=50&offset=150"
 }
}

Support Query Parameters for Filtering

Allow clients to filter results by relevant fields without requiring them to fetch all data and filter client-side:

GET /products?category=electronics&min_price=100&max_price=500&in_stock=true

Common filter patterns include equality checks, range queries (min/max), boolean flags, and full-text search. Support filtering on fields that clients frequently need to narrow down, but avoid exposing every internal field as a filter parameter.

Enable Field Selection and Partial Responses

Let clients specify exactly which fields they need, reducing response sizes for bandwidth-constrained clients:

GET /users?fields=id,name,email

This approach, supported by Microsoft's API design guidelines, significantly reduces payload sizes when clients only need specific data points rather than complete resource representations. For more on optimizing JavaScript performance, including efficient data handling patterns, see our guide on optimizing the V8 compiler.

5. Choose a Versioning Strategy

APIs evolve over time--new features are added, fields are modified, and occasionally breaking changes become necessary. A clear versioning strategy manages these changes without breaking existing integrations.

URI Versioning: Simple but Polluting

The most straightforward approach embeds the version in the URL path:

GET /v1/users
GET /v2/users

URI versioning is simple to implement and highly visible--clients know exactly which version they're using. However, it fragments the API surface and can complicate caching since different versions are technically different resources.

Header Versioning: Cleaner URIs

Header-based versioning keeps URLs clean while allowing version selection:

GET /users
Accept: application/vnd.example.v2+json

This approach preserves URL consistency and groups all versions under the same endpoint. However, it requires clients to handle headers correctly and can complicate debugging since the version isn't visible in the URL.

Media Type Versioning: The Most RESTful Approach

Using the Accept header to specify both version and response format provides the most precise control, aligning with REST principles and enabling content negotiation:

GET /users
Accept: application/vnd.example.v2+json

Deprecation and Sunsetting

Regardless of your versioning strategy, communicate deprecation clearly. Include deprecation warnings in responses (using custom headers or response bodies), provide migration timelines, and maintain backward compatibility during transition periods. Remove deprecated versions only when client usage justifies the breaking change.

6. Implement HATEOAS for Discoverable APIs

HATEOAS (Hypertext as the Engine of Application State) makes APIs self-documenting and navigable. Instead of requiring clients to know URLs upfront, responses include links to related resources and available operations.

Include Navigation Links in Responses

A well-designed response doesn't just return data--it provides context about what's possible next:

{
 "order": {
 "id": "ord_12345",
 "status": "processing",
 "total": 149.99,
 "links": [
 { "rel": "self", "method": "GET", "href": "/orders/ord_12345" },
 { "rel": "cancel", "method": "DELETE", "href": "/orders/ord_12345" },
 { "rel": "items", "method": "GET", "href": "/orders/ord_12345/items" },
 { "rel": "customer", "method": "GET", "href": "/users/usr_67890" }
 ]
 }
}

The rel (relationship) field describes what the link represents, while href provides the URL and method indicates the HTTP verb to use. This self-documenting approach, as described in Microsoft's API design documentation, reduces client-side hardcoding of URLs and allows your API to evolve without breaking clients that follow links dynamically.

Represent State Transitions

HATEOAS excels at modeling workflows where certain actions are available only in specific states. The cancel link only appears while the order is processing, not after it's shipped. This approach makes APIs more intuitive and reduces incorrect API calls by removing unavailable actions from view.

7. Optimize for Performance

API performance directly impacts user experience and operational costs. Consider caching, compression, and efficient data transfer strategies to minimize latency and bandwidth.

Leverage HTTP Caching

HTTP provides built-in caching mechanisms through headers like ETag, Last-Modified, and Cache-Control. Use ETag with conditional requests (If-None-Match) to enable efficient revalidation:

GET /users/123
ETag: "abc123"

# Subsequent request with caching
GET /users/123
If-None-Match: "abc123"
# Returns 304 Not Modified if unchanged

For collections that change infrequently, use Cache-Control headers to allow CDN caching while maintaining freshness through validation.

Support Compression

Enable gzip or Brotli compression for response bodies, significantly reducing bandwidth for JSON responses (typically 70-90% compression ratios). Most HTTP clients support automatic decompression, requiring no client-side changes.

Implement Async Operations for Long-Running Tasks

Some operations--report generation, file processing, batch operations--can't complete within normal request timeouts. For these cases, implement the 202 Accepted pattern: accept the request and return HTTP 202 with a status endpoint URL, process the operation in the background, and let clients poll the status endpoint for completion. When complete, the status endpoint returns the result or a download URL. This approach keeps your API responsive while handling computationally intensive tasks gracefully. For understanding how modern JavaScript handles asynchronous operations, see our guide on JavaScript Promises.

8. Design Consistent Request and Response Formats

Consistency across your API reduces cognitive load for developers and makes your API more predictable. Establish conventions and follow them rigorously.

Standardize Request Bodies

Use consistent naming conventions (camelCase, snake_case, or kebab-case) throughout your API and stick to one choice. Include required and optional fields clearly, and avoid mixing conventions within the same resource. Provide reasonable defaults for optional fields, reducing the information clients must supply while maintaining flexibility.

Create Predictable Response Structures

Establish patterns that clients can rely on across all endpoints:

{
 "data": { ... },
 "meta": {
 "page": 1,
 "total": 250
 },
 "links": {
 "self": "/users?page=1",
 "next": "/users?page=2"
 }
}

Consistent structures, as recommended by Swagger's best practices, allow clients to write generic response handlers that work across multiple endpoints without endpoint-specific parsing logic. If you're working with React applications, these patterns integrate well with modern state management approaches like React Query, which you can learn more about in our guide on using Suspense with React Query.

9. Document Your API Thoroughly

Documentation is as important as implementation. Even a perfectly designed API fails if developers can't understand how to use it.

Use OpenAPI Specification

OpenAPI (formerly Swagger) provides a standardized format for describing REST APIs. An OpenAPI definition can generate interactive documentation, client SDKs, and server stubs:

openapi: 3.0.0
info:
 title: User Management API
 version: 1.0.0
paths:
 /users:
 get:
 summary: List all users
 parameters:
 - name: limit
 in: query
 schema:
 type: integer
 default: 20
 responses:
 '200':
 description: Successful response

Provide Examples and Try-It Features

Good documentation includes example requests and responses for every endpoint. Interactive documentation (like Swagger UI) lets developers test API calls directly from the documentation, accelerating learning and troubleshooting.

Maintain Documentation Close to Code

When documentation lives separately from code, it quickly becomes stale. Tie documentation to code through inline annotations, automated generation from code comments, or continuous integration checks that verify documentation accuracy. For teams working with GraphQL alongside REST, our guide on GraphQL enums covers how similar documentation principles apply to GraphQL API design.

10. Secure Your API Properly

API security protects both your service and your users' data. Implement authentication, authorization, and data protection at every layer.

Choose Appropriate Authentication

For public APIs, OAuth 2.0 with client credentials or API keys provides token-based authentication with granular permissions. For internal services, mutual TLS or JWT tokens can provide strong authentication without token management overhead. Always use HTTPS--never transmit credentials or sensitive data over unencrypted connections.

Implement Authorization Checks

Authentication identifies who is making a request; authorization determines what they're allowed to do. Every endpoint should verify that the authenticated user has permission to access the requested resource. Implement resource-level authorization to ensure users can only access data they own.

Validate and Sanitize All Inputs

Treat all input as potentially malicious. Validate required fields, data types, and business rules. Sanitize inputs to prevent injection attacks. Return clear validation errors that help legitimate clients correct their requests while protecting your system from malicious input. For more on building secure, scalable backends, explore our web development services.