Networks and softwares are not as reliable as we would all love them to be. When your software is calling our API it can experience intermittent and unforeseen failures like network lag and jitter, or crash or whatever Murphy's law has up its sleeve.
Let's say you called our API to modify a user's custom properties. If the call fails before you can read the response, you wouldn't know whether the call succeeded or if it didn't even had a chance to be read by our servers. But that's not a big deal as you can rather safely retry it.
If you experienced that issue while starting a delivery of an important message to millions of devices at once? Did the delivery start? Did the call even reach the WonderPush API? Retrying that call could mean bothering millions of your users. As you received no answer you simply cannot tell.
Fortunately, we have rolled out a feature we call Idempotency Keys.
This enables you to identify a given call uniquely, and to ensure that WonderPush API will not treat your subsequent retries if it already successfully received any previous call.
It works exclusively on POST, PUT, PATCH and DELETE calls to the Management API. HEAD, GET and OPTIONS calls are idempotent by design (and any given indempotency key will be silently ignored), so this means that such calls can always be retried safely.
Simply add the X-WonderPush-Idempotency-Key header to your request, giving a maximum 64 character-long alphanumeric string. Underscores _ and dashes - are also allowed, letting you use any UUID/GUID or unpadded base64url values directly.
Failing to comply with the above restrictions will give you a 400 Bad Request HTTP error with a "12042" code.
Now 3 things can happen when the Management API received a call with a X-WonderPush-Idempotency-Key header:
- This is the first time WonderPush receives a call with this idempotency key.
The call proceeds as usual and there are no difference in the returned response. - The idempotency key is already known and the original request has completed.
Your receive the original response, along with two headers:X-WonderPush-Idempotency-Initially-Started-AtandX-WonderPush-Idempotency-Initially-Completed-At, containing HTTP date values just like the standardDateheader. - The idempotency key is already known and the original request has not completed yet.
You will receive a409 ConflictHTTP error with a"12045"code.
You can retry the call later to get a chance to read the original response.
Note that the idempotency key check is atomic and in case of simultaneous requests, only one will be taken as the first time WonderPush receives that call, the other would be returned as concurrent retries.
As a safety measure, we make sure the call being retried is the same as originally received, so make sure to retry the call in the exact same way. A simplement serialization difference for instance may result in the two calls mismatching. Failing that, you will receive a 400 Bad Request HTTP error with message "Idempotency key already associated to a different request" and code "12043".
We keep used idempotency keys around for 7 days.
You should generate a unique identifier, or you can hash your request.
If it can legally happen that you send the exact same call twice, we suggest that you incorporate the date of the event that trigger a delivery in the hash or idempotency key, so that you don't end up using the exact same idempotency key as another identical prior request. Otherwise the API could respond that the request was already processed some time ago (7 days at max), by returning the original response, just as if the call was successfully processed again.
Using this system you can safely replay requests and lower your timeout values to safely catch network failures earlier. Be sure in the later case to handle the "12045" error code as a success (that does not include the original response as its not ready yet).