Im not sure why people post these kinds of things. First of all it does not define really anything, it just gropes at the subject trying to find something to hold on to.

And of course theres the crazy web articles that made funny memes about cows multiplying by calling POST over and over.

So Im not going to actually get into any of that text book stuff because alot of it is actually described in academic language, or simply being metaphorical, or describing a “result” as this 5 min blog post did.

So heres what idempotent actually is:

ID - empotent

Means literally “empowered by ID”, or ID aware if that feels better to you. It means that things that have been created will not be recreated because an ID prevents that from happening. And thats all it means. To make that mean something in your app, you have to convert that to a semantic and hopefully contractual interaction.

For example lets use REST.

POST /addresses

{ "first-name": “bob", “last_name": “johnson”, “street”: “foo… }

201 CREATED: { “id”: "8c3d03c4-7fe7-4355-afd4-25e838c4f884" "first-name": “bob", “last_name": “johnson”, “street”: “foo… }

The server returns the ID of the created address, which should now forever identify this address.

So what happens if we do the POST to addresses again and omit the ID? We will be creating a new address we already created. This is exactly what should happen.

But what should happen if we call POST again with the ID?

POST /addresses { “id”: "8c3d03c4-7fe7-4355-afd4-25e838c4f884" "first-name": “bob", “last_name": “johnson”, “street”: “foo… }

You have some options for the response here. Here are some obvious choices:

409 CONFLICT 400 BAD REQUEST

The point being that POST should not process requests to create items that already have an ID assigned as provided by the client.

You can return a response like “Call PUT dummy” but thats not necessary.

And thats really it some shops sort of muddy the waters by saying that IDEMPOTENCY means “upsert”.

Again thats describing a behavior with an intended result not IDEMPOTENCY. While its technically true that APIs should when provided with the same input have the same output it doesnt mean you should code a POST as an upsert.

We have semantics for creates and updates already in REST. So be empowered by ids and make your apps semantics match.

user:	pudwallabee
created:	June 8, 2024
karma:	39