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 8

HTTP Methods: Semantics and Idempotency

Recommended resources

Welcome to the second module of our course, "RESTful API Design and Communication." In the previous module, we established a solid foundation by understanding the low-level mechanics of networking and server architecture, culminating in how modern servers use event-driven models to handle high concurrency. We've essentially built the engine; now, it's time to design the controls that allow clients to interact with it.

This lesson begins that journey. Our learning outcome is to explain HTTP method semantics and idempotency in the context of API design. We will explore the "verbs" of the web—the HTTP methods that define actions on resources. We'll then delve into a crucial concept for building robust APIs: idempotency. Mastering these fundamentals is non-negotiable for any backend interview, as they form the very language of RESTful services.

The Verbs of an API: HTTP Method Semantics

In REST, every action revolves around the concept of a resource, which is simply an object or representation of something (e.g., a user, a product, an order). HTTP methods are the verbs that specify what action to perform on that resource. Since you have a background in databases, you'll find a natural parallel here: these methods map directly to the familiar CRUD (Create, Retrieve, Update, Delete) operations.

A well-designed REST API uses these methods semantically, meaning the choice of method clearly communicates the intent of the request. Let's explore the primary methods.

The following video from ByteMonk provides a great overview of the main HTTP methods and how they relate to API design.

Mastering HTTP Methods: A REST API Deep Dive

This video offers a comprehensive deep dive into the most important HTTP methods, their purpose, and best practices for using them in a RESTful context.

Watch the video from the beginning until the end. Pay close attention to how each method—GET, POST, PUT, PATCH, and DELETE—is explained with examples and how they map to CRUD operations. This will set the stage for our discussion on idempotency.

As the video explained, the primary methods are:

  • GET: Retrieves a representation of a resource. This is a read-only operation.
  • POST: Submits data to a resource, most often to create a new subordinate resource. For example, POST /users would create a new user.
  • PUT: Replaces a resource with the request payload. If the resource does not exist, it may be created. For example, PUT /users/123 would replace the entire profile for user 123.
  • PATCH: Applies a partial modification to a resource. For example, PATCH /users/123 could be used to update only the user's email address.
  • DELETE: Removes a specified resource. For example, DELETE /users/123 would delete user 123.

Idempotency: Building Predictable and Fault-Tolerant APIs

Now we move to one of the most important—and frequently misunderstood—properties in API design: idempotency.

An HTTP method is idempotent if an identical request can be made once or multiple times with the same effect, leaving the server in the same state. This doesn't mean the response has to be identical every time (e.g., the first DELETE might return 204 No Content, while subsequent ones return 404 Not Found), but the state of the resource on the server remains the same after the first successful request.

Why does this matter? Networks are unreliable. A client might send a request, but a network glitch could prevent it from receiving the response. The client doesn't know if the request failed or if just the response was lost. In this situation, the client's only option is to retry. If the operation is idempotent, retrying is safe. If it's not, you might accidentally create multiple resources, charge a customer twice, or cause other unintended side effects.

This next video explains the concept of idempotency brilliantly, using practical examples like online payments to highlight its importance.

Idempotency - What it is and How to Implement it

This video by Alex Hyett clearly defines idempotency and walks through which common HTTP methods possess this property and why it's critical for robust systems.

Watch the sections that define the problem and evaluate the main HTTP methods, from the beginning of the video. This will solidify your understanding of which operations are safe to retry.

Idempotency of Common Methods

Let's formally classify the methods based on idempotency. The following article provides a clear, text-based summary.

Idempotency - What is an Idempotent REST API?

This article from restfulapi.net provides a concise and accurate breakdown of which HTTP methods are idempotent and why.

Read the introduction and then focus on the section Idempotency with HTTP Methods. This will walk you through the reasoning for GET, PUT, DELETE, POST, and PATCH.

To summarize and combine these insights:

  • Idempotent Methods:

    • GET, HEAD, OPTIONS, TRACE: These methods are read-only ("safe") and do not change the state of the server. Therefore, they are inherently idempotent.
    • PUT: Idempotent. If you send a PUT request to update a user's profile to a certain state, sending it again with the same data will result in the exact same final state.
    • DELETE: Idempotent. The first request deletes the resource. Any subsequent identical requests do not change the server state further; the resource simply remains deleted.

  • Non-Idempotent Methods:

    • POST: Not idempotent. Sending the same POST /users request multiple times will create multiple new users.
    • PATCH: Generally not idempotent. A PATCH request could contain an instruction like "increment the viewCount field," which would produce a different result each time. However, a PATCH that sets a field to a specific value (e.g., {"email": "new@example.com"}) behaves idempotently. The method itself is not guaranteed to be idempotent; it depends on the operation being performed.

The Venn diagram below provides a helpful visual distinction between methods that are "unsafe" (i.e., they change state) and those that are "idempotent". Notice the overlap.

This Venn diagram categorizes HTTP methods. Safe methods like GET are idempotent. Unsafe methods like POST and PATCH are not. PUT and DELETE are unsafe because they change state, but they are also idempotent because repeated calls have the same effect as a single call.

A Classic Interview Question: PUT vs. PATCH vs. POST

The distinctions between PUT, PATCH, and POST are a frequent source of questions in backend interviews. A clear understanding demonstrates your grasp of REST principles.

The image below summarizes the key differences between POST and PUT.

This table compares the POST and PUT methods, highlighting the key differences in idempotency, effect, target URI, and the result of repeated requests.

Let's dive deeper, especially into the PUT vs. PATCH comparison.

PUT Vs. PATCH: Key Differences in HTTP Methods for API ...

This article from Unstop provides an excellent, detailed comparison of PUT and PATCH, covering their definitions, use cases, and key differences, including a helpful comparison table.

Read the entire article, paying special attention to the Key Difference between PUT and PATCH table and the sections When to Use PUT? and When to Use PATCH?. Also, review the FAQs at the end for concise answers to common questions.

To crystallize the main points from the article:

  • Use POST when:

    • You are creating a new resource as a subordinate of a parent resource (e.g., creating a comment for a blog post: POST /posts/123/comments).
    • The server is responsible for generating the ID and full URI of the new resource.
    • The operation is not idempotent.

  • Use PUT when:

    • You need to completely replace an existing resource. The request body must contain the full new representation of the resource.
    • You are creating a resource where the client knows the final URI and ID (e.g., PUT /users/john.doe). This is less common for creation but is part of the specification.
    • The operation must be idempotent.

  • Use PATCH when:

    • You need to make a partial update to a resource (e.g., changing only a user's email address).
    • You want to be efficient with bandwidth by sending only the changed data.
    • The operation is not necessarily idempotent (e.g., incrementing a counter).

Conclusion

In this lesson, we established the fundamental vocabulary for designing RESTful APIs. You learned the specific meaning, or semantics, of the primary HTTP methods and how they map to standard data operations. More importantly, you now understand the critical concept of idempotency and its role in creating reliable, fault-tolerant systems that can safely handle network retries.

Key Takeaways:

  • HTTP methods are the verbs of your API: GET (retrieve), POST (create), PUT (replace), PATCH (partially update), and DELETE (remove).
  • Idempotency means that making the same request multiple times has the same effect on the server's state as making it once.
  • GET, PUT, and DELETE are idempotent, making them safe to retry.
  • POST and PATCH are generally not idempotent, requiring more careful handling on the client and server side to prevent unintended duplicates or state corruption.
  • The choice between PUT and PATCH depends on whether you are doing a full replacement or a partial update.

Now that we have a firm grasp of the "verbs" of REST, our next lesson will focus on the "nouns": Designing RESTful API endpoints following resource naming and URI conventions. We will learn how to structure clear, intuitive, and hierarchical URIs that make your API a pleasure to use.