REST API design for systems in HLD - System Design Guide

Problem Statement

When multiple systems or clients need to communicate, inconsistent or poorly designed APIs cause confusion, errors, and slow development. Without clear rules, APIs become hard to maintain, scale, and evolve, leading to integration failures and poor user experience.

Solution

REST API design uses a set of clear, consistent rules to structure how systems communicate over HTTP. It organizes resources with meaningful URLs, uses standard HTTP methods for actions, and defines clear request and response formats. This approach makes APIs predictable, easy to use, and scalable across different clients and servers.

Architecture

┌─────────────┐         ┌───────────────┐         ┌───────────────┐
│   Client    │ ───────▶ │  REST API     │ ───────▶ │   Backend     │
│ (Browser,   │         │  Server       │         │   Services    │
│  Mobile)    │         │               │         │               │
└─────────────┘         └───────────────┘         └───────────────┘
       ▲                      │  ▲  │                      │
       │                      │  │  │                      │
       │                      │  │  │                      │
       └──────────────────────┘  └───────────────────────┘

This diagram shows a client sending HTTP requests to a REST API server, which processes them and interacts with backend services to fulfill the requests.

Trade-offs

✓ Pros

→

Uses standard HTTP methods (GET, POST, PUT, DELETE) making APIs intuitive and easy to understand.

→

Stateless communication improves scalability and reliability by not storing client context on the server.

→

Clear resource-based URLs improve readability and organization of API endpoints.

→

Supports multiple data formats like JSON and XML for flexible client consumption.

✗ Cons

→

Statelessness can lead to repeated data transfer, increasing bandwidth usage for some operations.

→

Over-fetching or under-fetching data can occur if endpoints are not designed carefully.

→

Versioning APIs can become complex as the system evolves and backward compatibility is needed.

Use REST API design when building web services that require clear, scalable, and standardized communication between clients and servers, especially when supporting multiple client types like web and mobile apps.

Avoid REST APIs for real-time, low-latency communication needs such as live chat or gaming, where protocols like WebSockets or gRPC are more suitable.

Real World Examples

Amazon

Amazon uses REST APIs to allow third-party sellers and applications to interact with its marketplace services, enabling operations like product listing and order management.

Twitter

Twitter provides REST APIs for developers to access tweets, user profiles, and post updates, enabling a wide ecosystem of apps and integrations.

Stripe

Stripe uses REST APIs to let businesses integrate payment processing into their websites and apps with clear, consistent endpoints for transactions and customer management.

Alternatives

GraphQL

GraphQL allows clients to request exactly the data they need in a single query, unlike REST which has fixed endpoints.

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 over HTTP/2 for efficient, low-latency communication, unlike REST's text-based HTTP/1.1.

Use when: Choose gRPC for high-performance internal microservices communication or real-time systems.

Summary

REST API design organizes communication between clients and servers using standard HTTP methods and resource-based URLs.

It improves scalability and maintainability by enforcing stateless interactions and clear data formats.

REST is ideal for web services needing broad client support but less suited for real-time or highly interactive systems.

Practice

1. Which HTTP method is typically used to retrieve data from a REST API without modifying it?

easy

A. DELETE

B. POST

C. GET

D. PUT

Solution

1. Step 1: Understand HTTP methods in REST

   GET is used to request data without changing the server state.

2. Step 2: Match method to action

   POST creates or modifies data, PUT updates, DELETE removes data.

3. Final Answer:

   GET -> Option C

4. Quick Check:

   Retrieve data = GET [OK]

Hint: GET is for reading data only, no changes [OK]

Common Mistakes:

• Confusing POST with GET
• Using PUT for data retrieval
• Thinking DELETE retrieves data

2. Which of the following is the correct URL format to access a specific user with ID 123 in a REST API?

easy

A. /users/123

B. /users/getUser?id=123

C. /getUser/123

D. /users?id=123

Solution

1. Step 1: Identify RESTful URL design

   REST URLs use resource names and IDs as path segments, not actions or query for specific resource.

2. Step 2: Compare options

   /users/123 correctly points to user resource with ID 123; others use verbs or query parameters incorrectly.

3. Final Answer:

   /users/123 -> Option A

4. Quick Check:

   Resource ID in path = /users/123 [OK]

Hint: Use resource path + ID, avoid verbs in URL [OK]

Common Mistakes:

• Using verbs like getUser in URL
• Using query params for resource ID
• Mixing action names with resource paths

3. Given the following REST API call: DELETE /orders/456, what is the expected outcome?

medium

A. It deletes order 456 from the system

B. It updates order 456's status

C. It retrieves order 456's details

D. It creates a new order with ID 456

Solution

1. Step 1: Understand HTTP DELETE method

   DELETE is used to remove a resource identified by the URL.

2. Step 2: Analyze the URL and method

   /orders/456 points to order with ID 456; DELETE removes it.

3. Final Answer:

   It deletes order 456 from the system -> Option A

4. Quick Check:

   DELETE + resource ID = delete resource [OK]

Hint: DELETE method removes resource at given URL [OK]

Common Mistakes:

• Thinking DELETE retrieves data
• Confusing DELETE with POST
• Assuming DELETE creates or updates

4. A developer designed a REST API endpoint as POST /users/123/updateEmail to update a user's email. What is the main issue with this design?

medium

A. Using POST instead of GET for update

B. Including action 'updateEmail' in the URL violates REST principles

C. Missing user ID in the URL

D. Using query parameters instead of path variables

Solution

1. Step 1: Review REST URL design principles

   REST APIs should use resource paths, not actions in URLs.

2. Step 2: Identify the problem in the URL

   Including 'updateEmail' is an action, which breaks REST design; updates should use PUT or PATCH on /users/123.

3. Final Answer:

   Including action 'updateEmail' in the URL violates REST principles -> Option B

4. Quick Check:

   URLs represent resources, not actions [OK]

Hint: Avoid verbs in URLs; use HTTP methods for actions [OK]

Common Mistakes:

• Using verbs in URL paths
• Confusing POST with GET for updates
• Omitting resource IDs

5. You need to design a REST API for a system managing books and their authors. Which design best follows REST principles for retrieving all books by a specific author with ID 789?

hard

A. /books/authors/789

B. /books?author=789

C. /getBooksByAuthor/789

D. /authors/789/books

Solution

1. Step 1: Understand resource hierarchy in REST

   Authors and books are resources; books by an author are a sub-resource of author.

2. Step 2: Evaluate URL options

   /authors/789/books clearly shows books belonging to author 789, following REST resource nesting.

3. Step 3: Consider query vs path

   While query parameters can filter, nested resource path is more RESTful for related resources.

4. Final Answer:

   /authors/789/books -> Option D

5. Quick Check:

   Nested resource path shows relationship [OK]

Hint: Use nested paths for related resources [OK]

Common Mistakes:

• Using verbs in URL
• Overusing query parameters
• Ignoring resource relationships