
Idempotent Web APIs: What benefit do I get? - mfenniak
https://mathieu.fenniak.net/idempotent-web-apis-what-benefit-do-i-get/
======
mambodog
Some usability feedback: It seems like the most useful information is
contained in the links between nodes, but at first it was not obvious to me
that they were clickable, or that clicking the text links at the bottom of
node descriptions would actually show the 'link' description, rather than just
taking me to the next node.

I'd recommend you make it clearer that the linking lines between nodes are
clickable. Even better, rather than using a modal dialogue to display node
contents, you could use a popover with an arrow pointing to it's owner.
Clicking a link a the bottom of an item would simply move the popover, making
the relationships between various items of content clearer.

~~~
mfenniak
Thanks for the feedback. There are usability issues, and as you point out, the
importance of the links is not evident at a first glance. I like the popover
idea; I'll have to give that a try.

------
latch
I like the idea. Have you considered adding weights? I'd also consider linking
to a more detailed source (wikipedia?) when available.

On the topic of idempotence..we recently made our platform distributed across
4 datacenters using queues. None of us really knew what we were doing.
Recognizing this very early on, we made all calls idempotent. Pretty sure that
single decision is what made the entire system work.

~~~
mfenniak
I have absolutely considered adding weights. But, it quickly leads to the idea
that my priorities are not necessarily the same as everyone else's, and that
leads to user-customizing, and that leads to... well, it got to some cool
ideas, but I figured first I should shove this out the door in a simple form
and see if people like the concept. If the concept is well-received, I'll
continue to develop it and explore other API best practices in a similar
manner.

------
j-m-o
Awesome idea.

I know they don't get too much love on HN, but it would be cool to see this
done for a set of enterprise integration patterns.

See:

<http://www.eaipatterns.com/toc.html>

<http://camel.apache.org/enterprise-integration-patterns.html>

~~~
mfenniak
Thanks!

The enterprise integration patterns links are interesting to me; thanks for
point those out. I can definitely see how they could use a connection to
reality. I can look at a random one and see what it is, but understanding why
you'd use it is a mile above my head.

~~~
j-m-o
Some of the EIPs suffer from the same 'head-in-the-sky' issues as the GoF
design patterns, but there's a few that have come in handy (like the
idempotent receiver!).

The link to Apache Camel is a bit more informative with actual examples with
code snippets.

------
RyanMcGreal
Reply to mattacular, whose comment was deaded:

Idempotence (literally "same power) in a REST API means a given request
produces the same result whether you execute it once or multiple times. Given
the URL:

/resource/1

Whether you execute the DELETE method on that resource once or ten times, the
resource is deleted. Therefore, it is idempotent.

~~~
jmcqk6
This is something I've wondered about. So you get a DELETE request against
/resource/1 and you delete the resource. When you get the second DELETE
request, shouldn't that give a 404, since the resource no longer exists?

~~~
mAritz
Why give out an error at all? The intention of the API call is fulfilled
either way.

The spec regarding this: "A successful response SHOULD be 200 (OK) if the
response includes an entity describing the status, 202 (Accepted) if the
action has not yet been enacted, or 204 (No Content) if the action has been
enacted but the response does not include an entity."

204 is what I would return for most DELETEs because there is no status
(entity) left after a normal delete.

~~~
drone
The problem I find with this solution is that it makes it difficult to tell if
the client is operating properly. That is, I can't tell if my client is
spuriously trying to delete the same resources from the status codes if there
is no difference between a status code for successful deletion, and an attempt
to delete an object that does not exist.

As an API consumer, I would prefer a 404 not found - so that I may easily and
accurately populate up the information that a resource I expected to be there,
and to delete, wasn't there when I tried to delete it. Especially in complex
applications where various clients may be running against the same data set
across many distributed nodes, this can be demonstrative of many much harder-
to-find problems when every action is "success."

I also would prefer 200 - with a description of the entity that was deleted,
again, for verification and system maintenance needs.

~~~
dragonwriter
> That is, I can't tell if my client is spuriously trying to delete the same
> resources from the status codes if there is no difference between a status
> code for successful deletion, and an attempt to delete an object that does
> not exist.

Presumably, if you are logging status codes received by your client, you are
also logging the requests that produce them; you should be able to determine
if it is spuriously trying to delete the same resources from the request
history. The only status code you need to make this determination is the 2xx
received from the _first_ successful request.

~~~
drone
Experience has taught me that it is far easier to catch negative anomalies (an
apparently bad thing happened), than it is to catch positive anomalies (things
that look normal, but are actually bad).

Consider that to catch two nodes deleting the same resource, you'd need to
correlate the messages from all nodes. (Or, at least, know that there may be a
problem with nodes trying to delete the same resource, and plan by recording
every resource deleted in some other node.) Whereas, with a 404, you can
determine that there is a problem in one message - and have the resource
information to search through your history and find related events. Given that
some of the systems I've worked in have had thousands of nodes - I'd rather
not go through the log history from each node on every normal event to verify
that it isn't actually abnormal. At a certain scale, relying on correlation
and positive anomaly detection approaches such a level of difficulty as to be
nearly impossible.

~~~
dragonwriter
> Consider that to catch two nodes deleting the same resource, you'd need to
> correlate the messages from all nodes.

Generally, two nodes trying to delete the same resource isn't an anomaly. (The
result of those attempts being something other than the resource being deleted
exactly as if one attempt was made to deleted would be an anomaly, as it would
the same node attmepting to delete the node more than once after having
received confirmation that it had been deleted on an earlier effort.)

------
jamesaguilar
Very interesting, but I would say your tradeoffs aren't really accurate.
Idempotency should decrease testing and maintenance costs because it is
simpler.

------
amiheines
Interesting, Seems like the Haskel benefits but implemented in mortal
technologies.

------
hcarvalhoalves
I don't get why there should be an intrinsic higher development cost since
you're building a simpler, saner and better-defined system. If anything, it
would _decrease_ development costs.

~~~
akiselev
It will decrease development costs for the end users, but most times when you
say you want a simple api, you mean you want to take a really complicated
system and wrap it up in a far simpler interface (hence the "abstract" part).

Making good abstractions for a complicated system is always harder than just a
1:1 API.

------
mattacular
Could somebody explain how DELETE can be idempotent?

Ex. "Request = DELETE ID 1"

First request, ID 1 is deleted. Second request, ID 1 has already been deleted.
Third request, ID 1 has already been deleted.

------
ExpiredLink
What Is Idempotent in REST?

<http://www.infoq.com/news/2013/04/idempotent>

------
nahname
If you have to explain this to your boss, why is that person your boss?

~~~
GFischer
If you think technical prowess is a requirement for being a boss, reality is
going to be quite shocking for you.

And, I don't even think it should be a requirement (depending on the role), if
said boss hired you because you have the technical experience needed and
trusts you, and is willing to learn, I wouldn't mind working for him.

[http://management.fortune.cnn.com/2011/06/01/why-bosses-
dont...](http://management.fortune.cnn.com/2011/06/01/why-bosses-dont-need-to-
know-all-the-answers/)

~~~
nahname
I should have clarified, I fully appreciate that most bosses do not actually
know the technical minutia of their underlings. That is how hierarchies
work...

My question was really, given this shared understanding. Why is this limited
level of autonomy so common? How much longer can work that requires deep
technical knowledge be directed and controlled by those who do not understand
it.

In short, why are bosses not mentors. I don't mean in the general sense, I
mean literally. My boss should be the person I respect, not who I answer to.

~~~
mcherm
Then what term, if not "boss", do you use for someone who lacks technical
skills but has the skills to decide how to manage the investments and balance
profit against growth opportunities and for those reasons gives you direction
and instructions?

~~~
apalmer
Ehhh dont disagree with you on a theoretical level, but are the average
software development manager management skills sooooooo strong that it totally
overrides basic technical proficiency? definitely there are a individuals that
this is true for... but most development managers naw...

~~~
mcherm
Except in very rare cases where a company is staffed almost entirely by former
engineers, it is almost always the case that when you go far enough up the
management hierarchy you will encounter someone who is perfectly smart, but
doesn't happen to know why idempotent calls are useful (or even what
"idempotent" means). That is the person this chart is intended for. It may not
be your immediate boss, but perhaps HER boss, or another step up the chain.

------
dscrd
Couldn't we find a nicer word for "idempotent"?

~~~
daviddaviddavid
Indeed. It's a very clunky word, not least because it's unclear which syllable
to stress.

I've variously heard people say both i-dem-PO-tent and i-DEM-po-tent. (In the
latter, the "o" in "po" gets reduced to a schwa.)

~~~
riquito
Since when a noun pronounce should be obvious?

