Nonces
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 been supplied).
Last updated