How would you design a resource-creation call so that a client retrying after a network failure cannot create two records — by having the client choose the resource's URL and using PUT instead of POST to a collection?

## Why POST-to-collection is hazardous `POST /orders` means "process this per the collection's semantics", normally "create a new one". The server invents the identity, so the client has no name for what it may have created. After a timeout it has two bad options: retry and risk a second order, or give up and risk losing one. This is the double-submit hazard, and it appears equally from a user double-clicking Submit, an SDK auto-retry, a queue redelivery, or a proxy re-sending. ## The design move Give the client naming authority: 1. The client generates a UUIDv4 (or another collision-resistant identifier) **before** the first attempt. 2. It sends `PUT /orders/{id}` with the complete representation. 3. The server upserts at that key. Because `PUT` says "make the resource at this URL equal this state", replaying converges. Ten deliveries produce one order. The critical detail is *before the first attempt*. If the identifier were assigned by the server, the retry could not reuse it and the whole property collapses. ## Getting the status codes and preconditions right Use `If-None-Match: *` on a create-only write: it succeeds only when nothing exists at that URL. Then: - First write → **201 Created**, with the fresh `ETag`. - Replay of the same body → **200/204** (already in the desired state), or 201 again if you cannot distinguish; the client must treat both as success. - A different body at an existing URL → **412** if you enforce create-only, or an ordinary update if the endpoint is a genuine upsert. Pick one and document it, because "my retry" and "someone reusing my ID" otherwise look identical on the wire. Server-side, enforce it with a unique constraint on the primary key and map the constraint violation to the replay path rather than to a 500. Never implement it as "SELECT then INSERT": two concurrent retries can both pass the check. ## Where it fits and where it does not **Fits**: resources with natural or client-generatable identity — documents, orders, uploads, events from a producer that already has an event ID. It is also excellent for mobile and offline-first clients, which can create locally, keep working, and sync later against the same URL. **Does not fit**: when the identifier must be server-assigned (a human-facing sequential invoice number), when identity derives from server state, or when the operation is not a create at all — "capture this payment" is a command, not a resource you can name in advance. Those cases want the sibling idempotency-key approach or a reconciliation read. ## Security and hygiene A client-chosen key is attacker-influenced input. Use UUIDv4 or UUIDv7 rather than sequential or guessable values, validate the format strictly, and scope uniqueness per tenant if IDs are visible. Reject malformed or oversized inputs at the edge. And remember the URL is now stable and meaningful — it lands in logs and referrers, so do not encode anything sensitive in it. ## Related alternative: natural keys If the domain already has a unique business key — one enrollment per (user, course), one payment per invoice — a unique constraint on that key gives the same collapse for free, and the second attempt can return the existing resource. This is often the least machinery for the most safety, and it protects against duplicates from any source, not just retries.