REST API best practices in HLD - System Design Exercise

Design: REST API Design System

Design focuses on REST API best practices including endpoint design, security, versioning, error handling, and performance. Implementation details of backend services and databases are out of scope.

Functional Requirements

FR1: Design APIs that are easy to use and understand by developers

FR2: Support CRUD operations for resources

FR3: Ensure APIs are secure and handle authentication and authorization

FR4: Provide consistent and meaningful error responses

FR5: Support versioning to allow backward compatibility

FR6: Enable pagination, filtering, and sorting for list endpoints

FR7: Ensure APIs are performant with low latency

FR8: Provide documentation for API usage

Non-Functional Requirements

NFR1: Handle up to 10,000 concurrent API requests

NFR2: API response time p99 under 300ms

NFR3: Availability target of 99.9% uptime

NFR4: Support JSON as the primary data format

NFR5: Use standard HTTP methods and status codes

Think Before You Design

Questions to Ask

❓ Question 1

❓ Question 2

❓ Question 3

❓ Question 4

❓ Question 5

❓ Question 6

❓ Question 7

Key Components

API Gateway or Reverse Proxy

Authentication and Authorization Service

Rate Limiter

Logging and Monitoring

API Documentation Tool (e.g., OpenAPI/Swagger)

Backend Services handling business logic

Design Patterns

Resource-based URL design

Use of HTTP methods (GET, POST, PUT, DELETE, PATCH)

Statelessness in API design

Error handling with standard HTTP status codes

Versioning via URL path or headers

Pagination with limit and offset or cursor

Caching strategies

Reference Architecture

Client
  |
  v
API Gateway / Reverse Proxy
  |
  v
Authentication & Authorization Service
  |
  v
Backend Services
  |
  v
Database

Additional components:
- Rate Limiter attached to API Gateway
- Logging and Monitoring system connected to Backend Services
- API Documentation served via API Gateway

Components

API Gateway / Reverse Proxy

Nginx, Kong, or AWS API Gateway

Route requests, enforce rate limiting, handle SSL termination, and serve API documentation

Authentication & Authorization Service

OAuth 2.0, JWT tokens

Verify user identity and permissions before allowing access to APIs

Backend Services

RESTful web services built with frameworks like Express.js, Spring Boot, or Flask

Implement business logic and handle CRUD operations on resources

Database

Relational (PostgreSQL) or NoSQL (MongoDB)

Store persistent data for resources

Logging and Monitoring

ELK Stack, Prometheus, Grafana

Track API usage, errors, and performance metrics

API Documentation

OpenAPI (Swagger)

Provide interactive and up-to-date API usage documentation

Request Flow

1. Client sends HTTP request to API Gateway with resource URL and method

2. API Gateway authenticates request via Authentication Service using tokens

3. If authorized, API Gateway forwards request to appropriate Backend Service

4. Backend Service processes request, interacts with Database as needed

5. Backend Service returns response with appropriate HTTP status code

6. API Gateway applies rate limiting and caching if configured

7. API Gateway sends response back to Client

8. Errors are returned with standard HTTP status codes and JSON error messages

9. API Documentation is accessible via API Gateway endpoint

Database Schema

Key entities depend on API resources; for example, a User entity with fields (id, name, email, password_hash), and other resource entities with unique IDs and attributes. Relationships are defined as needed (1:N, N:N). The schema supports CRUD operations and indexing for efficient querying.

Scaling Discussion

Bottlenecks

API Gateway becoming a single point of failure under high load

Authentication Service latency affecting overall API response time

Database read/write bottlenecks with increasing data volume

Rate limiting causing request throttling during traffic spikes

Logging and monitoring overhead impacting performance

Solutions

Deploy API Gateway in a clustered, load-balanced setup with health checks

Use stateless JWT tokens to reduce authentication service calls; cache token validation results

Implement database read replicas and sharding; use caching layers like Redis

Use distributed rate limiting with token buckets and backoff strategies

Asynchronously process logs and metrics; use sampling to reduce volume

Interview Tips

Time: Spend 10 minutes understanding requirements and clarifying scope, 20 minutes designing the API best practices and architecture, 10 minutes discussing scaling and trade-offs, and 5 minutes summarizing.

Explain REST principles and importance of resource-based URLs

Discuss HTTP methods and status codes usage

Highlight security with authentication and authorization

Describe error handling and consistent response formats

Explain versioning strategies and why they matter

Mention pagination, filtering, and sorting for scalability

Talk about documentation and developer experience

Address scaling challenges and solutions realistically

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