REST API Idempotency - what is it and why does it matter?

REST API Idempotency - what is it and why does it matter?

Rest API idempotency simply states, that calling a request multiple times has the same effect, as calling it once.

In other words GET /books should return the same collection of books, even when I call it a second time right after it.

Think about this for a few seconds. There's a high chance you have already seen that one HTTP Verb is not idempotent by design. Got it?

It's the post request.

Since POST creates a new resource, calling it twice will lead to a different system state than calling it once.

Why does it matter?

Idempotency is a key design principle for REST APIs. Not least because we can't guarantee that all HTTP requests arrive at their destination.

Is POST always non-idempotent?

However, there are scenarios when you want your POST requests idempotent. For example payment transactions.

That's the point where idempotency keys come into play. It is used to determine whether the resource has already been created or not.


Designing a good API isn't a trivial task. Watch out for idempotency issues and tackle them asap. This will result in better software and happier clients.

Sign up for my newsletter, to never miss valuable knowledge!