Idempotent operations produce the same result even when the operation is repeated many times. The result of the 2nd, 3rd, and 1,000th repeat of the operation will return exactly the same result as the 1st time.

For example, simple mathematical examples of idempotency include:

x + 0;

x = 5;

In the first example, adding zero will never change the result, regardless of how many times you do it. In the second, x is always 5. Again, this is the case, regardless of how many times you perform the operation. Both of these examples describe an operation that is idempotent.

Did you know you can generate a full-featured, documented, and secure REST API in minutes using DreamFactory? Sign up for our free 14 day hosted trial to learn how! Our guided tour will show you how to create an API using an example MySQL database provided to you as part of the trial!

Create a REST API Now

Idempotency is important in APIs because a resource may be called multiple times if the network is interrupted. In this scenario, non-idempotent operations can cause significant unintended side-effects by creating additional resources or changing them unexpectedly. When a business relies on the accuracy of its data, non-idempotency posts a significant risk. 

Is hand-coding APIs taking up too much of your development time? DreamFactory enables non-coders to create REST APIs in minutes. Start your free 14-day hosted DreamFactory trial today

Idempotent vs. Safe

The concepts of ‘idempotent methods’ and ‘safe methods’ are often confused. A safe method does not change the value that is returned, it reads – but it never writes. Going back to our previous examples:

x + 0;

x = 5;

The first of these, adding zero, will return the same value every time (it is idempotent), and adding zero will have no effect on that value (it is also safe). The second example will return the same value every time (it is idempotent) but is not safe (if x is anything other than 5 before the operation runs, it changes x).

Therefore, all safe methods are idempotent, but not all idempotent methods are safe.

Idempotent Methods in REST

REST APIs use HTTP methods such as POST, PUT, and GET to interact with resources such as an image, customer name, or document. When using an idempotent method, the method can be called multiple times without changing the result.

For example, using GET, an API can retrieve a REST resource. This has no effect on the resource and can be repeated over and over – it is both idempotent and safe.

HTTP methods include:

  • POST – Creates a new resource. POST is not idempotent and it is not safe.
  • GET – Retrieves a resource. GET is idempotent and it is safe.
  • HEAD – Retrieves a resource (without response body). HEAD is idempotent and it is safe
  • PUT – Updates/replaces a resource. PUT is idempotent but it is not safe
  • PATCH – Partially updates a resource. PATCH is not idempotent and it is not safe.
  • DELETE – Deletes a resource. DELETE is idempotent but it is not safe.
  • TRACE – Performs a loop-back test. TRACE is idempotent but it is not safe.

As can be seen from this information, most of the methods used in a REST API are idempotent. The exception is POST. However, it is worth remembering that if used incorrectly, other methods like GET and HEAD can still be called in a non-idempotent way. Developers can avoid this by following REST principles.

Does your business need a better way to generate, publish, and manage its REST APIs? The DreamFactory platform enables businesses to generate fully-documented REST APIs quickly and easily. Click here to start your free 14-day hosted DreamFactory trial today.