In DNAnexus, a nonce is a string that uniquely identifies a request against
our API. The use of a nonce will ensure that regardless of how many times a
request is made, the result will be the same as a single successful request.
This is particularly useful for handling network failures. If a response is
dropped on its way back to the client, the client may reissue the request with
the nonce which our API will recognise as a previous request and return an exact
replica of the dropped response.
The routes that currently use this nonce field primarily revolve around project,
data object, and job creation. The use of a nonce with these routes will prevent
a client from accidentally creating multiple items when only one was intended.
The routes are as follows:
As a nonce is a unique identifier of a request, the input used in a request
should remain unchanged when retrying with a nonce. If any change is made
to the input, the API will consider it a separate and different request and
throw an InvalidInput error. Additionally, the nonce field may not exceed
128 bytes in a UTF-8 encoded string.
As nonces are intended to be used for recovery and retry of dropped requests
within a short span of time, the above behavior is only guaranteed if the second
request is issued within one hour of the original request. After that time, the
second request may result in a newly created object (as if the nonce had not