REST API design for systems in HLD - Architecture Diagram

System Overview - REST API design for systems

This system provides a REST API to allow users and applications to interact with backend services. It supports scalable, stateless communication using HTTP methods and JSON data format. Key requirements include handling many concurrent requests, ensuring security, and providing fast responses.

Architecture Diagram

User
  |
  v
Load Balancer
  |
  v
API Gateway
  |
  v
Authentication Service <--> Authorization Service
  |
  v
REST API Service
  |
  +--> Cache
  |
  +--> Database
  |
  +--> Message Queue
  |
  v
Response

Components

User

client

Initiates requests to the REST API

Load Balancer

load_balancer

Distributes incoming requests evenly across API Gateway instances

API Gateway

api_gateway

Routes requests, enforces rate limiting, and handles SSL termination

Authentication Service

service

Verifies user identity and issues tokens

Authorization Service

service

Checks user permissions for requested resources

REST API Service

service

Processes API requests, applies business logic, and interacts with data stores

Cache

cache

Stores frequently accessed data to reduce database load and improve response time

Database

database

Stores persistent application data

Message Queue

queue

Handles asynchronous tasks and decouples services

Response

client_response

Delivers processed data back to the user

Request Flow - 14 Hops

User → Load Balancer

Load Balancer → API Gateway

API Gateway → Authentication Service

Authentication Service → Authorization Service

Authorization Service → API Gateway

API Gateway → REST API Service

REST API Service → Cache

Cache → REST API Service

REST API Service → Database

Database → REST API Service

REST API Service → Message Queue

REST API Service → API Gateway

API Gateway → Load Balancer

Load Balancer → User

Failure Scenario

Component Fails:Database

Impact:New data writes fail and cache misses cannot be fulfilled, causing errors or stale data responses

Mitigation:Use database replication for failover; cache serves stale data for reads; queue asynchronous writes for retry

Architecture Quiz - 3 Questions

Which component is responsible for verifying user identity before processing the request?

A Authentication Service

B API Gateway

C Load Balancer

D Cache

Design Principle

This architecture demonstrates a scalable REST API design using layered components for security, caching, and asynchronous processing. It ensures statelessness, separation of concerns, and efficient request handling to support many users reliably.

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