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
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
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
field in UUID1 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.
All UUID versions are supported by most operations. However, there are a few instances where only UUIDv1 is supported. Please check the reference documentation for each create operation to see which UUID versions it supports. ↩