RESTful API
design & development
in Torrance

Networks fail in untidy ways. A client sends a request to create an order, and the connection drops before the reply arrives. Did the order get created? The client cannot tell. If it sends the request again, the customer may be charged twice. If it does not, the order may be lost.

Retries are unavoidable. Mobile connections drop, servers restart, load balancers time out. Any client that talks to an API over the internet will need to repeat some requests. The API design decides whether repeating a request is safe.

Some requests are safe by nature. Reading a record can be repeated as often as needed. Setting a field to a specific value gives the same result each time. The danger lies in requests that create something or trigger an action: payments, orders, messages, bookings.

An idempotency key solves this. The client generates a unique value for each operation and sends it in a header. The server stores the key with the result. If the same key arrives again, the server returns the stored result instead of repeating the action. Several large payment APIs use this pattern.

Details matter. How long are keys stored? A day is common, long enough to cover any reasonable retry. What happens if the same key arrives with a different request body? The safe answer is an error, because it suggests a bug in the client.

Concurrent requests need care. Two retries can arrive at the same time, before the first has finished. The server must lock on the key so that only one proceeds, and the other waits or receives a clear conflict response.

Clients need guidance too. Documentation should say which operations accept idempotency keys, how to generate them and when to retry. Good practice is exponential backoff: wait a little, then longer, then longer still, with some randomness so that thousands of clients do not retry at the same moment.

Status codes tell the client what to do. Errors caused by a bad request should not be retried, because they will fail again. Timeouts and temporary server errors can be.

Webhooks face the same problem in reverse. The sender retries when it gets no reply, so the receiver will sometimes get the same event twice. Every event should carry a unique ID, and receivers should record processed IDs and ignore repeats.

Test failures on purpose. Drop connections halfway, delay responses, send the same request twice in parallel. Problems that appear once in ten thousand requests in production are easy to reproduce in a test, and much cheaper to fix there.

Adding idempotency after launch is possible, but every client must be updated to send keys. Designing it in from the first version avoids a slow migration later.

Keys should be generated on the client, not requested from the server. A random value such as a UUID is enough. The key must be created once for each logical operation and reused for every retry of that operation. A client that creates a fresh key on each attempt gets no protection at all.

Responses should make repeats visible. When the server returns a stored result, a header noting that the response was replayed helps the client developer understand what happened. It also helps support staff when a customer asks why an action seems to have run only once after several attempts.

Background jobs inside the API need the same protection. A job that sends an email or charges a card may itself be retried by the queue after a crash. Recording that the step was completed, and checking that record before acting, stops the same message or charge from going out twice.

Logs and metrics complete the picture. Counting how often keys are reused, and which clients reuse them most, shows where networks are unreliable or where a client has a bug. A sudden rise in replays after a release is an early warning that something changed.

Batch endpoints need a plan too. When a client sends a list of items in one request and the request fails halfway, it must be clear which items were processed. Returning a result for each item, with its own status, lets the client retry only the failures instead of the whole batch.

Clock and ordering issues follow retries. A late retry can arrive after a newer update to the same record. Version numbers or timestamps on writes let the server refuse a stale change instead of overwriting fresh data with old values.

Client libraries can take care of much of this. An official library that generates keys, retries with backoff and handles replayed responses spares every integrator from writing the same logic, and usually writing it with bugs. Even a short code sample that reuses one key across attempts reduces the number of duplicate operations the support team has to untangle later.

Support teams benefit as well. When a customer reports a double charge or a missing order, the stored key and its recorded result show at once whether the client sent one operation or two. That turns a long investigation into a quick lookup.