HTTP method semantics, safe, idempotent, PUT vs PATCH vs POST

You phone the florist about your standing Friday order. The line is bad, so sometimes you cannot tell whether they heard you.

At the florist's phone	In the system
"What's on my Friday order?": the florist only reads it out	GET, safe (step 1)
"Make Friday's order twelve white tulips": said twice, still twelve white tulips	PUT (steps 3, 7)
the line crackles before the florist answers, so you say it again	resending after a lost reply (step 5)
"Cancel Friday's order" twice; the second time: "there's nothing to cancel"	DELETE: another reply, the same state (step 4)
"Send my mother a bouquet" twice: two bouquets arrive	POST (step 6)
"make the ribbon blue" against "add three roses"	a patch that sets against one that adds (step 9)
after "twelve white tulips", the vase you ordered last week is off the order	PUT drops what it leaves out (step 7)
your partner changes the order to lilies; then your crackly repeat of "tulips" gets through	a delayed replay (step 11)

In real terms: before letting anything resend a request automatically, check that the server's state after two copies equals its state after one.

Breaks down when: you picture the florist recognising your voice and ignoring a second "send a bouquet". A server does not do that unless you give it a way to (step 14).

Contrasting case: a request whose reply arrived. Nothing is resent, so idempotency makes no difference to it.

4.1 ExamHall: submitting an attempt

EXH-1380: the candidate app submitted with POST /attempts/a-7/submit, which recorded a submission and queued grading on every call. On flaky exam-hall Wi-Fi, a lost reply was resent. MR !1580 makes the submission a resource.

4.1 submit attempt a-7; the first reply is lost and the client sends the same request again
  as shipped   POST /attempts/a-7/submit        server answered 201, 201 · client saw lost, then 201 Location /submissions/2 · submissions 2 · grading jobs 2
  merge patch  PATCH /attempts/a-7              server answered 200, 200 · client saw lost, then 200 · submissions 0 · grading jobs 1
  MR !1580     PUT /attempts/a-7/submission     server answered 201, 204 · client saw lost, then 204 · submissions 1 · grading jobs 1

The POST ran twice (step 6). The PUT and the merge patch {"status":"submitted"} can be repeated, because both handlers queue grading only when the state first changes (steps 10, 12).

4.2 Each method, sent once and then retried

4.2 each request once, then again after a lost reply: is the server state the same as after one?
  GET /attempts/a-7                                                           replies 200 then 200 · same state: true
  PUT /attempts/a-7/answers/q4 {"text":"Demand falls"}                        replies 201 then 204 · same state: true
  DELETE /attempts/a-7/flags/q9                                               replies 204 then 404 · same state: true
  PATCH merge-patch+json {"note":"seat 14"}                                   replies 200 then 200 · same state: true
  PATCH json-patch+json [{"op":"add","path":"/reviewed_by/-","value":"p-3"}]  replies 200 then 200 · same state: false (reviewed_by ["p-3"] vs ["p-3","p-3"])
  POST /attempts/a-7/extra-time {"minutes":5}                                 replies 200 then 200 · same state: false (extra_minutes 5 vs 10)
  the server's own access log for GET: 1 row after one request, 2 after the retry (not part of the resource state)
  merge patch on a list: reviewed_by ["p-1"], then {"reviewed_by":["p-3"]} sent twice -> reviewed_by ["p-3"] (the list is replaced whole)

Replies differ on the PUT and the DELETE, yet the state matches (step 4). Replies match on the append and the POST, yet the state does not (steps 6, 9). The access log is the server's own business (step 1). A merge patch that names a list repeats safely, but it replaces the whole list: "p-1" is gone (step 9).

4.3 What idempotent does not promise

4.3 answer q4 from two devices: the phone's reply is lost, the laptop saves, then the phone retries
  phone PUT "Demand falls" lost · laptop PUT "Demand falls as prices rise" 204 · phone retry 204
  stored answer: "Demand falls" (the laptop's newer text is gone)

Each PUT was idempotent, but a late repeat undid a newer write (step 11). Guarding against that is api-optimistic-concurrency-etag's job.