REST API best practices in HLD - Scalability & System Analysis

Scalability Analysis - REST API best practices

Growth Table: REST API Scaling from 100 to 100M Users

Users	Traffic Characteristics	API Server Load	Database Load	Network	Other Changes
100 users	Low requests/sec (~10-50)	Single server handles easily	Single DB instance, low QPS	Minimal bandwidth	Basic logging, no caching needed
10,000 users	Moderate requests/sec (~1,000-5,000)	Multiple API servers behind load balancer	DB handles ~1,000 QPS, may need read replicas	Moderate bandwidth, consider CDN for static	Introduce caching (Redis), rate limiting
1,000,000 users	High requests/sec (~100,000+)	Horizontal scaling of API servers, autoscaling	DB bottleneck likely, sharding or partitioning needed	High bandwidth, CDN critical for static and some API responses	Advanced caching, API gateway, throttling, monitoring
100,000,000 users	Very high requests/sec (millions)	Global distributed API servers, multi-region load balancing	Multiple DB clusters, geo-distributed, complex sharding	Very high bandwidth, multi-CDN strategy	Microservices, event-driven, circuit breakers, extensive monitoring

First Bottleneck

At small to medium scale, the database is the first bottleneck. It struggles to handle increasing query volume and complex joins. API servers and network usually handle load better initially. Without caching, DB load grows linearly with users.

Scaling Solutions

• Horizontal scaling: Add more API servers behind load balancers to handle more concurrent requests.
• Caching: Use Redis or Memcached to cache frequent API responses and reduce DB load.
• Database read replicas: Offload read queries to replicas to reduce primary DB load.
• Sharding/Partitioning: Split database by user ID or region to distribute load.
• CDN: Cache static assets and some API responses close to users to reduce latency and bandwidth.
• API Gateway: Manage rate limiting, authentication, and routing efficiently.
• Monitoring and throttling: Detect and control traffic spikes to protect backend.

Back-of-Envelope Cost Analysis

• At 10,000 users, expect ~1,000 QPS. One DB instance can handle ~5,000 QPS, so still okay.
• At 1M users, ~100,000 QPS likely. Need ~20 DB replicas or sharded clusters.
• Bandwidth: 1 Gbps = 125 MB/s. For 100,000 QPS with 1 KB response, need ~100 MB/s bandwidth.
• API servers: Each handles ~5,000 concurrent connections. For 100,000 QPS, need ~20 servers.
• Caching reduces DB QPS by 50-90%, lowering infrastructure cost.

Interview Tip

Structure your scalability discussion by first identifying the main components: API servers, database, network. Then estimate load at different user scales. Identify the first bottleneck (usually DB). Propose targeted solutions like caching, read replicas, and sharding. Discuss trade-offs and monitoring. Keep explanations simple and focused.

Self Check

Question: Your database handles 1000 QPS. Traffic grows 10x. What do you do first?

Answer: Introduce caching to reduce DB queries and add read replicas to distribute read load. This relieves DB pressure before considering sharding or more complex solutions.

Key Result

The database is the first bottleneck as user traffic grows; applying caching and read replicas early effectively delays costly sharding and complex scaling.

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