Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 55

Designing RESTful APIs

Recommended resources

Hello! In our last lesson, we explored the crucial protocols—OAuth 2.0 and OpenID Connect—that govern who can access your application's resources. We focused on securing the front door. Today, we're stepping inside to design the layout of the rooms.

Your learning outcome is to design resource-oriented URIs with appropriate HTTP methods and status codes. For a mid-to-senior engineering interview, this is a foundational skill. Demonstrating a command of these REST principles shows that you can design APIs that are not only functional but also intuitive, scalable, and maintainable for any client that needs to interact with them.

1. The Core Principle: APIs are for Resources, Not Actions

The most important shift in thinking for RESTful API design is to stop thinking about actions (or functions) and start thinking about resources. A resource is a "thing" or a noun in your system. It could be a user, an order, a product, or any other entity.

The Uniform Resource Identifier (URI) should identify the resource, while the HTTP method should specify the action you want to perform on that resource.

A common mistake is to put verbs in the URI, like this:

  • POST /createUser
  • GET /get-all-orders

This is an anti-pattern. The correct, resource-oriented approach is to use the URI to name the noun (resource) and the HTTP method as the verb (action).

API Design in System Design Interviews w/ Meta Staff Engineer

To start, let's watch a segment from a video tailored for system design interviews. It clearly explains the concept of a 'resource' and the fundamental rule of using plural nouns in your URIs.

Watch from 04:16 to 05:50. Pay close attention to how the system's core entities (nouns) directly map to API resources and the 'plural nouns, not verbs' rule.

2. Designing Clean and Predictable URIs

Once you've adopted a resource-oriented mindset, the next step is to structure your URIs in a clean, consistent, and predictable way. This makes your API intuitive for other developers to use.

Web API Design Best Practices - Azure Architecture Center

The Microsoft Azure Architecture Center provides an excellent set of best practices for defining resource URIs. This text will give you a solid foundation for designing professional-grade APIs.

Read the section titled 'Define RESTful web API resource URIs'. Focus on the key naming conventions: Using nouns for resource names. Using plural nouns for collections (e.g., /orders). How to represent relationships (e.g., /customers/5/orders). The advice to keep URIs simple and avoid deep nesting.

Here's a summary of key URI design rules, which are perfect to have ready for an interview:

  • Use plural nouns for collections:
    • Good: /users, /orders
    • Bad: /user, /orderList
  • Use path parameters for specific items:
    • GET /users/{userId} retrieves a specific user.
  • Use nested paths for relationships:
    • GET /users/{userId}/accounts retrieves all accounts for a specific user.
    • Keep it shallow: Avoid overly complex nesting like /customers/1/orders/99/products. A better approach is to provide one level of nesting and then use links or subsequent calls.
  • Use lowercase letters: URIs are case-sensitive. Sticking to lowercase avoids confusion.
  • Use hyphens (-) to separate words: This improves readability.
    • Good: /user-profiles
    • Bad: /user_profiles, /userProfiles
  • Do not use file extensions: The client should rely on the Content-Type header to determine how to parse the response, not the URI.
    • Good: /users/123
    • Bad: /users/123.json

3. The Verbs: Using HTTP Methods Correctly

With well-designed URIs for our resources, we now select the appropriate HTTP method to perform an action. Each method has a specific semantic meaning.

9 Must-Know REST API Design Principles for Developers

This video provides a quick, clear summary of the primary HTTP methods and their intended use, including the important concept of idempotence.

Watch from 00:11 to 01:03. This will give you a high-level overview of GET, POST, PUT, PATCH, and DELETE.

Now, let's dive deeper. Understanding the nuances, especially idempotence, is critical for senior-level interviews. An operation is idempotent if making the same request multiple times produces the same result as making it once.

Method Action Idempotent? Typical Use Case
GET Read Yes Retrieve a representation of a resource or a collection. GET /users/123.
POST Create No Create a new resource within a collection. The server determines the URI. POST /users with user data in the body.
PUT Replace Yes Completely replace an existing resource at a known URI. PUT /users/123 with the full updated user object.
PATCH Update No Partially update an existing resource. PATCH /users/123 with only the fields to be changed (e.g., {"email": "..."}).
DELETE Delete Yes Remove a resource at a specified URI. DELETE /users/123.
Test your understanding!

An interviewer asks: "Explain the difference between PUT and PATCH. When would you choose one over the other?"

Show answer

You would say:

"PUT is used to replace an entire resource. When a client sends a PUT request to /users/123, the request body must contain the complete representation of user 123. If any field is omitted, it's considered a request to clear that field. PUT is idempotent because sending the same complete payload multiple times will always result in the same final state for the resource.

PATCH, on the other hand, is used for partial updates. The request body only needs to contain the specific fields that are being changed. This is more network-efficient if you are only updating one or two fields of a large object. PATCH is not necessarily idempotent; for example, a PATCH request to increment a counter would produce a different result each time it is sent.

I would choose PUT when the client has the full state of the object and wants to ensure it is completely replaced. I would choose PATCH for efficiency when only a few fields need to be modified, which is a very common use case in modern applications."

4. The Response: Communicating with HTTP Status Codes

After processing a request, the server must tell the client what happened. HTTP status codes are the standard mechanism for this communication. Using them correctly is essential for building robust clients.

For an interview, you don't need to memorize all 60+ status codes, but you absolutely must know the most common ones and the classes they belong to.

  • 2xx (Success): The request was successfully received, understood, and accepted.
  • 4xx (Client Error): The request contains bad syntax or cannot be fulfilled. The client is at fault.
  • 5xx (Server Error): The server failed to fulfill an apparently valid request. The server is at fault.

Here are the essential codes to know:

Code Meaning Common Use
200 OK Success The standard response for successful GET, PUT, or PATCH requests.
201 Created Resource Created The response for a successful POST request. The response should also include a Location header pointing to the new resource's URI (e.g., Location: /api/users/456).
204 No Content Success, no body A successful request where there's no data to return. Most commonly used for successful DELETE requests.
400 Bad Request Client Error The server cannot process the request due to a client-side error (e.g., malformed JSON, validation failed).
401 Unauthorized Authentication Required The client must authenticate to get the requested response. (You need to log in).
403 Forbidden Not Permitted The client is authenticated, but does not have permission to access the resource. (You're logged in, but you're not an admin).
404 Not Found Resource Not Found The server cannot find the requested resource. This is for GET /users/999 where user 999 doesn't exist.
500 Internal Server Error Server Error A generic error message for an unexpected condition on the server (e.g., an unhandled exception).

5. Putting it all together

Let's summarize these principles with a concrete example for a products API.

REST API Design Best Practices Cheatsheet
This cheatsheet provides a great visual summary of the core principles we've discussed, from noun-based resource names to standard status codes.

Example: /products resource

Operation HTTP Method & URI Request Body Success Response Error Response
Get all products GET /products None 200 OK with a list of products in the body. 500 Server Error
Create a new product POST /products Product data 201 Created with the new product and Location header. 400 Bad Request
Get a single product GET /products/{id} None 200 OK with the product data. 404 Not Found
Fully replace a product PUT /products/{id} Full product data 200 OK with the updated product. 404 Not Found
Partially update a product PATCH /products/{id} Partial product data 200 OK with the updated product. 404 Not Found
Delete a product DELETE /products/{id} None 204 No Content with an empty body. 404 Not Found

Conclusion

You have now learned the fundamental building blocks of high-quality REST API design. By internalizing these principles, you can discuss and design APIs in a way that signals experience and a deep understanding of web standards.

Key Takeaways for Your Interview:

  • Resources are Nouns: URIs identify resources (nouns), not actions (verbs). Use plural nouns for collections (e.g., /customers).
  • Methods are Verbs: Use HTTP methods (GET, POST, PUT, PATCH, DELETE) to express the action to be performed on the resource.
  • Understand Idempotency: Be ready to explain the concept and articulate the difference between idempotent (PUT, DELETE) and non-idempotent (POST) methods.
  • Use Status Codes Correctly: Communicate outcomes clearly using standard HTTP status codes, especially 200, 201, 204, 400, and 404.
  • Keep URIs Clean: Use lowercase, hyphens for separation, and avoid file extensions or implementation details.

Preview of the Next Lesson:
Designing a great API is the first step. But what happens when business requirements change and you need to modify the structure of a resource? If you just change it, you might break existing clients. In our next lesson, we will address this by comparing and contrasting different API versioning strategies to manage the evolution of your API gracefully.