Idempotent is a cool word I love to pronounce.  In fact, I wish I could write idempotent all over this article, and say it out loud over and over again, but then that would be waste.

From wikipedia:

“Idempotence is the property of certain operations in mathematics and computer science, that can be applied multiple times without changing the result beyond the initial application.”

In RESTful services, an HTTP Method is idempotent if it can be called many times without a different outcome, except for the first time.  This applies only to the result, and not the actual resource you are calling.  Let’s take a look at the following:

a. result = 5;

b. result++;

Example a. is idempotent because the result you are getting back will never change. In it’s initial application or call, it was assigned the value 5, but after that, the value of result will always be 5.  The variable result will always be 5, no matter if you call it 5 or 100 times.  On the other hand, b is not idempotent because the value of result will change with every call.  Here’s the caveat though, both a and b are considered “non-safe”, because they are both changing the value of the variable result. a is using the assignment statement, and b is using the postfix increment, which also modifies the result variable.

In using the example above, let’s apply this to HTTP VERBS.  When building an API, it’s important to know which VERBS are  Idempotent and/or safe.

Here is a list of some of the HTTP VERBS:

HTTP Method Idempotent Safe
OPTIONS yes yes
GET yes yes
HEAD yes yes
PUT yes no
POST no no
DELETE yes no
PATCH no no

 

From my experience, if you want to create a resource, you should use a Non-Idempotent HTTP VERB.  For example, let us say you want to make a database call to insert a record into a database.  When making an HTTP call, you should use an HTTP POST.  This is where fault tolerance handling comes in.  Suppose you send an HTTP POST Request, and you get a timeout?  Will the data be updated?  What if the timeout didn’t happen on the request, but on the response?  That means you could potentially insert the resource more than once.   HTTP POSTS may not be safe to retry, and you have to program around this to make sure you don’t start inserting data erroneously.

I don’t think you should use HTTP GET to modify data.  HTTP GETs should be used to request resources, and the method should not modify any data.  HTTP GETS can be cached, whereas HTTP POSTs cannot.  If you try to do the following: http://somesite.com/api/article/1234/delete, and use an HTTP GET, this method could potentially get cached, and not call the actual server to delete the data.   But if an HTTP VERB is non safe and non idempotent, then it will never be cached.

When building a REST API, a standard which I’ve seen and I try to follow is to avoid doing:

POST http://example.com/order/1/delete

instead do the following:

DELETE http://example.com/order/1

When updating a resource, don't do:

POST http://www.somesite.com/cart/1/update

but

PUT http://www.somesite.com/cart/1/

I am the first to admit, that I have not always followed these standards, but I am beginning to do it now. When following these standards, for example using HTTP DELETE to delete a resource, once it is deleted, you can’t delete it again.  Same with updating a resource using the HTTP PUT verb.  Your API CRUD semantics should not trump HTTP.  Using HTTP methods themselves for your APIs are best practice.

 

References:

http://restcookbook.com/HTTP%20Methods/idempotency/

https://www.twilio.com/engineering/2013/11/04/http-client

http://stackoverflow.com/questions/12142652/what-is-the-usefulness-of-put-and-delete-http-request-methods

 

 

Idempotent – REST Service Fundamentals

Leave a Reply

Your email address will not be published. Required fields are marked *