REST API best practices in HLD - System Design Guide

Problem Statement

APIs that do not follow clear conventions cause confusion for developers, leading to inconsistent usage, harder maintenance, and increased bugs. Without best practices, APIs can become difficult to scale, secure, and evolve over time.

Solution

Following REST API best practices means designing APIs with consistent URL structures, using proper HTTP methods, clear status codes, and meaningful error messages. This approach makes APIs predictable, easier to use, and maintainable, while supporting scalability and security.

Architecture

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│   Client App  │──────▶│   REST API    │──────▶│   Database    │
└───────────────┘       └───────────────┘       └───────────────┘
       ▲                     │  ▲  │
       │                     │  │  │
       │                     │  │  └─ Uses HTTP methods (GET, POST, PUT, DELETE)
       │                     │  └──── Returns proper status codes (200, 404, 500)
       │                     └────── Uses consistent URL paths (/users, /orders)
       └───────────────────────────────────────────────────────────────

This diagram shows a client making requests to a REST API, which uses consistent URLs and HTTP methods to interact with the database and returns appropriate status codes.

Trade-offs

✓ Pros

→

Improves developer experience with predictable and consistent API behavior.

→

Simplifies client-server communication by using standard HTTP methods and status codes.

→

Enhances scalability by stateless interactions and clear resource modeling.

→

Facilitates easier debugging and monitoring through standardized error handling.

✗ Cons

→

Strict adherence can limit flexibility for complex operations that do not map well to REST.

→

Overhead of designing and documenting APIs to meet best practices can increase initial development time.

→

May require additional tooling or middleware to enforce standards and handle errors uniformly.

Use REST API best practices when building public or internal APIs expected to serve multiple clients, require scalability, and need long-term maintainability.

Avoid strict REST best practices for simple, internal-only APIs with limited clients or when using protocols better suited for real-time or complex interactions like gRPC or WebSockets.

Real World Examples

Amazon

Amazon uses REST APIs with clear resource-based URLs and HTTP methods to manage product catalogs and orders, ensuring consistent integration across services.

Twitter

Twitter’s REST API uses standard HTTP verbs and status codes to allow developers to interact with tweets, users, and timelines predictably.

Stripe

Stripe’s payment API follows REST best practices with clear error messages and consistent resource naming to simplify payment processing integration.

Alternatives

GraphQL

GraphQL allows clients to request exactly the data they need with a single endpoint, unlike REST which uses multiple endpoints per resource.

Use when: Choose GraphQL when clients require flexible queries and want to reduce over-fetching or under-fetching of data.

gRPC

gRPC uses binary protocol and supports streaming, unlike REST which is text-based and stateless.

Use when: Choose gRPC for high-performance internal microservices communication requiring low latency.

Summary

REST API best practices ensure APIs are consistent, predictable, and easy to maintain.

They use standard HTTP methods, clear URL structures, and proper status codes for communication.

Following these practices improves scalability, developer experience, and long-term API health.

Practice

1. Which HTTP method is typically used to update an existing resource in a REST API?

easy

A. PUT

B. GET

C. POST

D. DELETE

Solution

1. Step 1: Understand HTTP methods for REST

   GET retrieves data, POST creates new resources, PUT updates existing resources, DELETE removes resources.

2. Step 2: Identify method for updating

   PUT is the standard method to update or replace an existing resource in REST APIs.

3. Final Answer:

   PUT -> Option A

4. Quick Check:

   Update = PUT [OK]

Hint: Update resource? Think PUT method [OK]

Common Mistakes:

• Confusing POST with update instead of create
• Using GET for updates
• Using DELETE to update

2. Which of the following is the correct way to version a REST API in the URL?

easy

A. /v1/api/resource

B. /api/resource/v1

C. /api/v1/resource

D. /api/resource?version=1

Solution

1. Step 1: Understand common versioning patterns

   Versioning is often done in the URL path to clearly separate API versions.

2. Step 2: Identify correct version placement

   Placing version immediately after the base API path, like /api/v1/resource, is standard practice.

3. Final Answer:

   /api/v1/resource -> Option C

4. Quick Check:

   Version in path = /api/v1/ [OK]

Hint: Version goes right after /api/ in URL path [OK]

Common Mistakes:

• Putting version after resource name
• Using query parameters for versioning
• Placing version before /api/

3. Given the following API response status codes, which one indicates a successful resource creation?

{
  "status": 201,
  "message": "Created"
}

medium

A. 200 OK

B. 201 Created

C. 400 Bad Request

D. 404 Not Found

Solution

1. Step 1: Review HTTP status codes for success

   200 means success for general requests, 201 means resource created successfully.

2. Step 2: Match status code to creation

   201 Created is the correct code to indicate a new resource was successfully created.

3. Final Answer:

   201 Created -> Option B

4. Quick Check:

   Creation success = 201 [OK]

Hint: 201 means resource created successfully [OK]

Common Mistakes:

• Confusing 200 with creation success
• Using 400 or 404 for success
• Ignoring status code meaning

4. A developer designed a REST API endpoint as POST /users/delete to delete a user. What is the best fix to follow REST API best practices?

medium

A. Change to GET /users/delete

B. Keep POST /users/delete but add a query param

C. Use PUT /users/delete

D. Change to DELETE /users/{id}

Solution

1. Step 1: Identify correct HTTP method for deletion

   DELETE method is the standard for removing resources in REST APIs.

2. Step 2: Correct endpoint structure

   Use resource identifier in URL path like /users/{id} with DELETE method for clarity and REST compliance.

3. Final Answer:

   Change to DELETE /users/{id} -> Option D

4. Quick Check:

   Delete resource = DELETE /resource/{id} [OK]

Hint: Use DELETE method with resource ID in URL [OK]

Common Mistakes:

• Using POST for delete actions
• Using GET to delete resources
• Adding delete action in URL path

5. You want to design a REST API that returns a list of products with optional filtering by category and price range. Which approach follows REST API best practices?

hard

A. GET /products?category=electronics&min_price=100&max_price=500

B. POST /products/filter with JSON body containing filters

C. GET /products/filter/category/electronics/price/100-500

D. PUT /products with filter parameters in the body

Solution

1. Step 1: Understand filtering in REST APIs

   Filtering is best done using query parameters in GET requests to keep APIs simple and cacheable.

2. Step 2: Evaluate options for filtering

   GET /products?category=electronics&min_price=100&max_price=500 uses GET with query parameters, which is standard and clear. Other options misuse POST or PUT or complex URL paths.

3. Final Answer:

   GET /products?category=electronics&min_price=100&max_price=500 -> Option A

4. Quick Check:

   Filter with GET query params [OK]

Hint: Use GET with query parameters for filtering [OK]

Common Mistakes:

• Using POST or PUT for filtering
• Embedding filters in URL path segments
• Sending filters in request body for GET