Retrying Safely

Vera is rehearsing in the sandbox and sends the POST that reserves bike bk_0977 at Old Market — and nothing comes back. The terminal waits, then times out. Her finger goes to the up-arrow key to bring the command back and send it again — and stops there, because she has just realized she does not know whether the first attempt reserved the bike or not. This page is about that exact hover.

Two things in your house answer this question for you. Hold a light switch down all day and the lamp is simply on; pressing it again changes nothing that was not already changed. Press a doorbell a second time "just to be sure" and somebody comes to the door twice. Requests come in both kinds, and knowing which one your finger is on — before you press again — is the whole of this topic.

The Verb Answers First

Chapter 2 sorted the verbs by intention, and that sorting turns out to have been about money all along. A GET asks a question; asking twice gets you the same answer twice and changes nothing in the world. A PUT sets a resource to exactly the value you supply, so setting it to the same value again lands you where you already were. A DELETE removes something, and removing an already-removed thing leaves it removed.

POST is the odd one out, because POST creates. Sending it again does not repeat a fact, it manufactures a second thing. Two reservations, two orders, two emails. The verb you used is therefore the first question to ask when a request dies without answering, and most of the time it settles the matter on its own.

The Word for It: Idempotent

The profession has a word for the light-switch property, and it is worth owning because you will meet it in documentation constantly. An action is idempotent when repeating it changes nothing after the first time. Flipping a switch to on is idempotent; ringing a doorbell is not.

GET, PUT and DELETE are idempotent by design, and the people who wrote the rules of HTTP intended them that way. POST is deliberately not. From here on the book uses the real word, and so should you — "is this endpoint idempotent?" is a short question that saves long conversations.

After the Ambiguous POST, Look

So the timeout hit a POST. Do not resend it. Instead go and find out what actually happened, using the safest thing you own: a question. Vera asks Tandem for any reservations attached to bike bk_0977, and the answer settles it in one line.

curl -i -H "Authorization: Bearer tnd_test_..." \
  "https://sandbox.api.tandem.example/v1/reservations?bike_id=bk_0977"

HTTP/1.1 200 OK
Content-Type: application/json

{"data": [{"id": "res_3f81", "bike_id": "bk_0977",
           "station_id": "st_014", "status": "active"}]}

The reservation is there, and it is res_3f81 — the same sandbox id from Chapter 3, which means the first attempt succeeded and only its answer was lost on the way back. Vera has nothing left to do but keep the id. Had the list come back empty, she would have known the attempt never landed, and could have sent it once more with a clear conscience.

Look before you act. It costs one harmless request and it replaces a guess with a fact, which is the trade this entire book keeps recommending.

How Grown-Up APIs Solve It

Some APIs offer a better tool, and you should recognize it when the documentation hands it to you. The idea is called an idempotency key: a value you invent yourself and attach to a creating request, unique to that one attempt. If the same key arrives twice, the server understands that this is a repeat of a single attempt rather than a second attempt, and returns the original result instead of creating a duplicate.

That turns a doorbell back into a light switch, and it means a lost answer can be safely re-sent. You will find it in the reference page for the endpoint, usually as an optional header, and using it costs you nothing but the discipline of generating a fresh value per real attempt. Designing such a system is a builder's job and lives in a different book; recognizing the offer, and taking it, is squarely yours.