Idempotent requests

Introduction to idempotent requests

All requests that mutate or create data on the DriveWealth platform support an additional Idempotency-Key header to help in preventing duplicate submissions of requests. Should a network interruption occur, or you otherwise lost a response from a DriveWealth API, you can safely perform the request provided that you send the same value as the Idempotency-Key.

To perform an idempotent request, provide an additional Idempotency-Key: header to the request. All POST requests accept Idempotency keys. Using Idempotency keys in GET or DELETE requests should be avoided.

POST /back-office/orders HTTP/1.1
--header 'dw-client-app-key: ${appKey}'
--header 'Accept: application/json'
--header 'dw-auth-token: ${authKey}'
--header 'Idempotency-Key: 418a5506-256c-4c3c-9d4d-f491522cf7f2'
--header 'dw-request-timestamp: 2019-06-25T23:40:12.345Z'
--data `{
  "accountNo": "DWPH000003",
  "orderType": "MARKET",
  "symbol": "AMZN",
  "side": "BUY",
  "amountCash": 100,
}`

Using DriveWealth Idempotency Keys

DriveWealth Idempotency Keys are saved for 4 days. Within this time period, sending any request with a duplicate key will return the exact same response as the original request, including the same status code and payload.

⚠️
Warning: Retries after 4 days are treated as new requests
Idempotency protection expires after 4 days. If you retry a request using the same Idempotency-Key after this window has passed, DriveWealth no longer recognizes the key and processes the request as a new request. The original response will not be returned, and the action (for example, placing an order) may be performed again.
To avoid unintended duplicate actions:

Do not retry a request after the 4-day window without first confirming the status of the original request (for example, by querying the relevant resource).

Best practices

Use randomly-generated UUIDs to prevent collisions.
Keys must be at least 16 characters in length.
Use exponential backoff or a similar pattern of requests for retries.
Use dw-request-timestamp as additional protection against technical failures.
Do not reuse an Idempotency-Key after 4 days. A retry after that point is a new request.

dw-request-timestamp

While idempotency keys will only be stored for 4 days, you may avail yourself of the dw-request-timestamp header to help avoid other technical failures that would resubmit old requests. For example, if you have a message-queue-based system for issuing requests to DriveWealth and are concerned about the possibility of repeating old requests, store the original timestamp in each message as this header. When DriveWealth sees this timestamp, it will reject the request if it is older than the 4-day idempotency limit.

Note that when requests are rejected for this reason, the original response contents will no longer have been preserved, and will not be sent back to you.

Retrying requests

Idempotency allows you to create a network layer that automatically retries all DriveWealth requests when you fail to receive a response. Please keep in mind that requests should never be unconditionally retried, as failing to receive a response does not necessarily mean that DriveWealth is not receiving and responding.

Your network layer should have a maximum number of retries before it gives up and follows other failover procedures. More importantly, retrying multiple times immediately may be futile—if there is a network issue or connectivity issue, it may not be resolved within the maximum number of retries if these requests are issued in quick succession. We recommend an exponential backoff or similar pattern of requests, such as:

(T) : Issue 1st request
(T+1s): Retry 1
(T+3s): Retry 2
(T+10s): Retry 3
(T+30s): Retry 4

Note: The retry schedule above falls well within the 4-day idempotency window. If your system retries later than 4 days after the original request (for example, from a message queue or a manual replay), the retry is treated as a new request. See the warning in Using DriveWealth Idempotency Keys.

dw-request-id

The dw-request-id is a header value that