REST API best practices in HLD - Cheat Sheet & Quick Revision

Recall & Review

beginner

What does REST stand for and what is its main purpose?

REST stands for Representational State Transfer. It is a design style for building scalable web services that use standard HTTP methods to perform operations on resources.

beginner

Why should REST APIs use nouns instead of verbs in their endpoint URLs?

REST APIs use nouns to represent resources because HTTP methods (GET, POST, PUT, DELETE) already define the action. This keeps URLs simple and consistent, like '/users' instead of '/getUsers'.

intermediate

What HTTP status code should be returned after a successful resource creation?

The HTTP status code 201 Created should be returned after successfully creating a resource. It indicates the request was successful and a new resource was created.

intermediate

Explain the importance of versioning in REST APIs.

Versioning helps manage changes in the API without breaking existing clients. It allows developers to introduce new features or fix bugs while supporting older versions.

intermediate

What is the benefit of using pagination in REST API responses?

Pagination limits the amount of data returned in a single response, improving performance and reducing bandwidth. It helps clients handle large datasets efficiently.

Which HTTP method is typically used to update an existing resource in a REST API?

A GET

B DELETE

C POST

D PUT

PUT is used to update an existing resource or create it if it does not exist.

What should a REST API return when a requested resource is not found?

A 404 Not Found

B 403 Forbidden

C 500 Internal Server Error

D 200 OK

404 Not Found indicates the requested resource does not exist.

Which of the following is a good practice for REST API URL design?

A /updateUser

B /getUserDetails

C /users/123

D /deleteUser

REST APIs use nouns and resource identifiers like '/users/123' instead of verbs.

Why is it important to use consistent HTTP status codes in REST APIs?

A To make debugging harder

B To clearly communicate the result of a request

C To confuse clients

D To avoid using HTTP methods

Consistent status codes help clients understand the outcome of their requests.

What is the main reason to include versioning in REST API endpoints?

A To support multiple API versions without breaking clients

B To slow down the API

C To make URLs longer

D To hide the API structure

Versioning allows evolving the API while keeping old versions functional.

Describe the key principles of REST API design and why they matter.

Think about how REST uses web standards to keep APIs simple and reliable.

Explain how to handle errors in a REST API and why proper error handling is important.

Consider how clients react when something goes wrong.

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