Idempotency Keys are useful on 'mutating endpoints' – that is, endpoints where something changes each time you make a request to it.
For example, the order creation endpoint. Every time you send a request to this endpoint you, in theory, want a new order created.
But when it comes to cancelling an order, that isn't the case. If you re-send a request to cancel an order… well, it won't end up double-cancelled. It'll be the same amount of cancelled whether it's the first request or the thousandth (but please try not to cancel an order 1000 times), so this endpoint doesn't need idempotency keys to protect it.
So which endpoints can I use idempotency keys with?
Right now, you can use these keys on the order creation and ping endpoints.
The /api/ping endpoint doesn't need the protection idempotency keys provide, but it gives you a safe, consequence-free endpoint to test your implementation with. You can confirm whether you're getting the same response back by making sure the timestamp in the response is the same.
When extending our API, we'll add idempotency key support to any new mutating endpoints that are not already idempotent by nature. For example, the order cancellation endpoint is naturally idempotent on its own, as are other GET endpoint (viewing orders, getting a quote, etc). If we were implementing an order-updating endpoint though, we'd add idempotency keys to it.
Now let's explain how to generate and send an idempotency key when you make a request.