Idempotency

Idempotence in the context of Web APIs refers to operations which when repeated provide exactly the same result. In practical terms, if my intention is to create a single item using a remote API and my first attempt provides a network error response, I need to know that when I retry I will not end up creating two or more identical items.

At Invopop, we take this very seriously and have designed support for idempotency in all API calls.

REST actions like GET and DELETE are inherently idempotent, fetching or deleting the same item twice will simply result result in the same response.

Update actions, such as PATCH are also usually idempotent. Duplicating calls may be inefficient, but we’ve made sure that in our API update actions are safe to be repeated.

Create actions, like POST or PUT however require additional gurantees to ensure data will not be duplicated. The Invopop APIs handle these scenarios by requiring that every model and thus every incoming operation includes an id field in UUID¹ string format. If the same create request is made twice with the same ID, and assuming none of the fields have changed, the second request will simply return the same response as the first.

If a create request is made with an existing ID and a different payload, the api will respond with a 409 Conflict response, allowing you to double check what might have gone wrong. If the data changes, the request is not idempotent!

Many APIs we’ve seen offer the ability to provide something like an Idempotency-Key in the header. This works, but adds additional complication to the client, and we felt for our use could more easily be handled by the ID fields typically included in models.