Idempotency

Idempotency is the notion of submitting the same request multiple times, but having the same effect as if it was only executed once, returning the same response every time. This allows an API client to retry requests that fail for transient reasons, e. g. one of the Fallacies of distributed computing.

Idempotency in the API is facilitated using an opt-in mechanism for all POST requests: a custom HTTP header (X-Request-Id) that can be sent as part of requests that wish to be retryable.

POST /api/v1/Exchanges/Create HTTP/1.1
Host: portal.wearefreemarket.com
Authorization: Bearer {authToken}
Content-Type: application/json
X-Request-Id: 0bb488c4-50eb-4809-a119-c30392b8eec8

{
    "AccountId": 12345,
    "Goal": 10000,
    "SourceCurrencyCode": "EUR",
    "TargetCurrencyCode": "GBP",
    "GoalType": "Sell"
}

Note

The value of the X-Request-Id header has to be unique (a GUID).

Using this custom header makes sure that every subsequent request to this endpoint with that same X-Request-Id value will never create another exchange (apart from the first one), and will return the same response as the first request.