1. Home
2. web
3. Best Practices for Designing REST API Endpoints

Introduction

In modern web development, API consistency plays a critical role in developer productivity.

Inconsistent endpoints (URLs), improper HTTP methods, and wrapping all errors in 200 OK status codes lead to confusion, bugs, and wasted development cycles.

This article reviews the best practices for designing scalable, self-documenting REST APIs that are easy to understand and integrate.

1. Principle 1: Resource-Oriented URLs (Use Nouns)

The core principle of REST is that URIs represent resources (nouns), while the HTTP methods (verbs) represent the actions performed on those resources.

Endpoints to Avoid (Verbs in the URL)

• POST /getUsers (Get users list)
• POST /deletePost?id=123 (Delete a post)
• POST /create_comment (Create a comment)

Mixing action verbs into the URL creates redundant endpoints and breaks standard naming patterns.

Optimized Design

Standardize on plural nouns for resources, and let the HTTP method dictate the operation.

• Use Plural Nouns: Standardize on plural nouns (e.g., /users, /posts, /comments) to maintain routing consistency across your API.

2. Principle 2: Proper HTTP Method Usage & Idempotency

When modifying resources, it is important to understand the semantic differences between HTTP methods and respect their idempotency.

• PUT (Replace): Replaces the entire target resource with the uploaded payload. This operation is idempotent because sending the same request multiple times yields the same state.
• PATCH (Partial Update): Applies partial modifications to a resource.
• POST (Create): Submits data to create a new resource. This operation is non-idempotent because repeating the request will result in multiple resource instances.

Respecting these method semantics allows client applications to safely retry failed network requests.

3. Principle 3: Leveraging HTTP Status Codes

Do not wrap all API responses in a 200 OK code while embedding the actual error status inside the JSON payload. This is a common anti-pattern.

Anti-Pattern Response

• HTTP Header: 200 OK
• Response Body:

  {
    "status": "error",
    "errorCode": 404,
    "message": "User not found"
  }
  

Standard API Status Codes

• 200 OK: The request succeeded (commonly used for GET, PUT, and PATCH).
• 201 Created: A new resource was successfully created (used for POST).
• 204 No Content: The request succeeded, but there is no payload to return (used for DELETE).
• 400 Bad Request: The client sent invalid payload parameters (validation failures).
• 401 Unauthorized: The request lacks valid authentication credentials.
• 403 Forbidden: The client is authenticated but does not have permission to access the resource.
• 404 Not Found: The requested resource does not exist.
• 500 Internal Server Error: A generic error indicating a server-side crash or database failure.

4. Principle 4: Filtering, Sorting, and Pagination

When retrieving a collection of resources (e.g., /posts), avoid creating custom endpoints for sorting or filtering. Instead, use query parameters.

Examples of Query Parameters

• Filtering: GET /posts?category=tech (Get only tech posts)
• Sorting: GET /posts?sort=-createdAt (Sort by creation date descending)
• Pagination: GET /posts?page=2&limit=20 (Fetch page 2 with a limit of 20 items)

5. Principle 5: API Versioning

To prevent breaking client applications when updating your API schema, always include versioning. The most common approach is path versioning:

• Path Versioning: /api/v1/users

This allows you to deploy a new version (/api/v2/...) while keeping /api/v1/ active for older clients.

Conclusion

Designing clean, consistent REST API endpoints simplifies integration and reduces onboarding time for new developers.

1. Represent resources using plural nouns in the URI path.
2. Communicate results using standard HTTP status codes (201, 400, 403, 404).
3. Use query parameters for filtering, sorting, and pagination.

Following these guidelines will help you build a maintainable and developer-friendly API.