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.