REST API design for systems in HLD - System Design Exercise

Design: REST API Design for Systems

Design focuses on the REST API layer including endpoints, request/response structure, authentication, and versioning. Backend implementation details and database design are out of scope.

Functional Requirements

FR1: Design a REST API to allow clients to perform CRUD operations on system resources.

FR2: Support authentication and authorization for secure access.

FR3: Provide pagination, filtering, and sorting for list endpoints.

FR4: Ensure API responses follow consistent and clear structure with proper HTTP status codes.

FR5: Support versioning to allow backward compatibility.

FR6: Handle error reporting with meaningful messages.

FR7: Allow rate limiting to protect the system from abuse.

Non-Functional Requirements

NFR1: API should handle up to 10,000 concurrent clients.

NFR2: Average API response time should be under 200ms (p99).

NFR3: Availability target is 99.9% uptime (about 8.77 hours downtime per year).

NFR4: API must be stateless to support horizontal scaling.

NFR5: Use JSON as the data exchange format.

Think Before You Design

Questions to Ask

❓ Question 1

❓ Question 2

❓ Question 3

❓ Question 4

❓ Question 5

❓ Question 6

Key Components

API Gateway or Load Balancer

Authentication and Authorization service

REST API endpoints and controllers

Request validation and error handling middleware

Rate limiting middleware

API versioning mechanism

Design Patterns

Stateless server design

Resource-based URL design

HATEOAS (Hypermedia as the Engine of Application State)

Pagination with limit and offset or cursor

Error handling with standard HTTP status codes

API versioning via URI or headers

Reference Architecture

Client
  |
  v
API Gateway / Load Balancer
  |
  v
Authentication Service <--> Authorization Service
  |
  v
REST API Server (handles versioning, routing, validation, rate limiting)
  |
  v
Backend Services / Databases (out of scope)

Components

API Gateway / Load Balancer

Nginx / AWS ALB / Kong

Distributes incoming requests, handles SSL termination, and routes to REST API servers.

Authentication Service

OAuth 2.0 Server / JWT Provider

Validates client credentials and issues tokens for secure access.

Authorization Service

RBAC or ABAC system

Checks if authenticated users have permission to access requested resources.

REST API Server

Node.js / Spring Boot / Django REST Framework

Implements REST endpoints, handles versioning, request validation, pagination, filtering, sorting, and error handling.

Rate Limiting Middleware

Redis-based token bucket or leaky bucket algorithm

Prevents abuse by limiting the number of requests per client in a time window.

Request Flow

1. Client sends HTTP request to API Gateway with authentication token.

2. API Gateway routes request to REST API Server.

3. REST API Server validates token with Authentication Service.

4. Authorization Service checks user permissions for requested resource.

5. Rate limiting middleware tracks request count and blocks if limit exceeded.

6. REST API Server processes request: applies pagination, filtering, sorting as needed.

7. REST API Server queries backend services or databases (out of scope).

8. REST API Server formats response with consistent JSON structure and appropriate HTTP status code.

9. Response sent back through API Gateway to client.

Database Schema

Out of scope for this design. Focus is on API layer.

Scaling Discussion

Bottlenecks

API Gateway can become a single point of failure or bottleneck under high load.

Authentication and Authorization services may slow down request processing if not optimized.

Rate limiting middleware may cause latency if centralized and not distributed.

REST API servers may become overwhelmed with concurrent requests.

Solutions

Use multiple API Gateway instances behind a load balancer for high availability and scalability.

Cache authentication tokens and authorization decisions to reduce repeated checks.

Implement distributed rate limiting using Redis clusters or in-memory stores close to API servers.

Scale REST API servers horizontally with stateless design and auto-scaling groups.

Interview Tips

Time: Spend 10 minutes clarifying requirements and constraints, 20 minutes designing the API architecture and data flow, and 15 minutes discussing scaling and trade-offs.

Explain REST principles and why statelessness is important for scalability.

Discuss how authentication and authorization protect the API.

Describe how pagination, filtering, and sorting improve usability and performance.

Highlight the importance of consistent error handling and versioning.

Address how rate limiting protects the system and how it can be implemented efficiently.

Talk about scaling strategies and how to avoid bottlenecks.

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