Designing an Interface to Call
There Are Only Two Questions Worth Asking About Any Operation, and Neither of Them Is What It Is Called
Last timeNaming the Things
Classifying every operation by whether it changes anything and by what repeating it does, why that classification decides who may retry, and what to do with the operations that fail both tests.
The two questions
An operation has a name, and the name is the least informative thing about it.
Two questions tell you nearly everything you need to know.
Does it change anything observable. If not, it is safe, and a caller may run it
freely, a proxy may cache it, and a crawler may follow it.
Does running it twice leave the state the same as running it once. If so, it is
repeatable. This is the question that matters, and it is independent of the
first: everything safe is repeatable, but plenty of things that change the
world are repeatable too.
| safe | repeatable | a caller may retry freel | needs a key to be repeat | |
|---|---|---|---|---|
| read one thing | 1 | 1 | 1 | 0 |
| replace a thing entirely | 0 | 1 | 1 | 0 |
| delete a thing | 0 | 1 | 1 | 0 |
| create a thing, server c | 0 | 0 | 0 | 1 |
| add an amount to a balan | 0 | 0 | 0 | 1 |
| set a status to shipped | 0 | 1 | 1 | 0 |
| send a confirmation mess | 0 | 0 | 0 | 1 |
Two entries on that list are worth examining. Replacing a thing entirely is
repeatable because the second call writes the same bytes over the same bytes.
Adding an amount is not, because the second call adds again, and the
difference between the two is not how dangerous they are but whether the
operation describes a destination or a movement.
Deleting is repeatable even though the second call finds nothing there. The
state afterwards is the same either way, which is all repeatability asks. The
common objection, that the second call returns a different answer, confuses the
response with the state, and the property is about the state.
Why it decides who may retry
The reason to care is the one thing every network does, which is fail to tell
you what happened.
The lesson stops here
3 more paragraphs to go
You have read the opening. The rest of the argument, the problems that check whether it landed, and the lines worth keeping at the end all come with a plan.
The first lesson of every course in the library reads the whole way through, free, so you can see exactly what the rest of them are.
See the planThe contentsThis is the reading half
Starting the course gives you your own copy of it. Every idea on every page has problems standing under it, marked with a reason rather than a tick, and any sentence you do not believe can be opened and argued with. None of that can happen on a page nobody owns.
The contents