What are Idempotent and Safe methods of HTTP and REST

In order to efficiently work with REST and RESTful web service, good knowledge of HTTP is really helpful. Even though REST seems easy, designing a uniform and consistent RESTful API is a tough job. One of the tricky tasks is choosing right the HTTP method for right job e.g. when to use PUT vs POST. Once you know the meaning and purpose of different HTTP methods, it helps to choose the right method for the right job. You can divide HTTP methods into two main categories safe and idempotent. Safe methods are HTTP methods that do not modify the resource e.g. a GET request  is safe because it doesn't modify the resource you are requesting e.g. data of a Book. Another safe HTTP method is HEAD, which doesn't change the resource representation on the Server, but all other HTTP methods e.g. POST, PUTor DELETE are non-safe.

Coming to idempotent methods, they are HTTP methods which can be called multiple times and they will produce the same result. They are considered the safe option to update a resource on the Server.

Some examples of idempotent HTTP methods are GET, PUT, and PATCH. No matter how many times you call them, they will produce the same result with same URI. You should also read HTTP: The Definitive Guide by David Gourley to learn more about HTTP methods in detail. It's absolutely critical to understand the HTTP protocol in depth to design better RESTful API.

Difference between idempotent and safe methods in HTTP

Let's see a couple of more details about Idempotent and safe methods in HTTP and REST WebServices.

What is Safe Methods in HTTP

These are HTTP methods which don't change the resource on the server side. For example using a GET or a HEAD request on a resource URL should NEVER change the resource. Safe methods can be cached and prefetched without any repercussions or side-effect to the resource . Here is an example of safe method

GET /order/123 HTTP/1.1

This will retrieve the order with orderId 123. No matter how many times you execute this method, the order in the server will not be modified or impacted. That's why GET method is a safe method.

What are Idempotent Methods in HTTP

These are methods which are safe from multiple calls i.e. they produce same result irrespective of how many times you call them. They change the resource in Server every time you call them but the end result is always same. Maths is good place to explain idempotent methods, consider the following example:

int i = 30; // idempotent

i++; // not idempotent

Here the assignment operation is idempotent, no matter how many times you execute this statement, i will always be 4. The second example is not idempotent. Executing this 10 times will result in a different outcome as when running 5 times. Since both examples are changing the value of i, both are non-safe methods.

Idempotency is an important thing while building a fault-tolerant RESTful API. Idempotency is also the reason of why should you use PUT over POST to update a resource in REST.

For example, suppose a client wants to update a resource through POST. Since POST is not an idempotent method, calling it multiple times may result in incorrect updates.

In the real world its quietly likely that your POST request may timeout, what will happen to the resource that. Is the resource actually updated? Does the timeout happened during sending the request to the server, or the response to the client?

Can we safely retry again, or do we need to figure out first what has happened with the resource? By using idempotent methods like PUT, you don't have to answer this question, but we can safely resend the request until we actually get a response back from the server.

You can also read RESTful Web Services by Leonard Richardson, Sam Ruby, and David Heinemeier Hansson for more details on HTTP and REST mapping.


Here is nice overview of which HTTP methods are safe and Idempotent:
  • GET is both Safe and Idempotent.
  • HEAD is also both safe and idempotent.
  • OPTIONS is also safe and idempotent.
  • PUT is not safe but idempotent.
  • DELETE is not safe but idempotent.
  • POST is neither safe nor idempotent.
  • PATCH is also neither safe nor idempotent.
Here is a slide which explains which methods of HTTP protocol are safe and which are Idempotent

Difference between HTTP Safe and Idempotent methods REST

That's all about the safe and idempotent methods in HTTP and REST. Remember, safe methods doesn't change the representation of the resource in Server e.g. GET method will not change the content of the page your accessing. They are the read-only methods of the object-oriented programming world.

Similarly, idempotent methods will not throw different outcome even if you call them multiple times. They are safe for updating resource on Server. They will always return the same result unless you change the URL. 

P.S. - If you want to learn how to develop RESTful Web Services using Spring Framework, check out Eugen Paraschiv's REST with Spring course. He has recently launched the certification version of the course, which is full of exercises and examples to further cement the real world concepts you will learn from the course.


Nikolay Georgiev said...

Hi. First you say "Some examples of idempotent HTTP methods are GET, PUT, and PATCH." but then you say also say "PATCH is also neither safe nor idempotent.".
I guess in the first statement you mean HEAD instead of PATCH.

Javin Paul said...

@Nikolay, good spot, Yes, It should be GET, PUT and HEAD, which are idempotent mehtods in HTTP.

Unknown said...

Nice explanation!!

Post a Comment