The Idempotency-Key HTTP header field
Question: this says a duplicate request MUST respond with the previous result on retry. Doesn’t this run the risk of returning bad data to the client in the event that the API result includes the “current state” of some resource? And by that I mean if I call this API to make a change and get back the current state of the resource, and I retry my request after some other change has occurred, since this must return the previous result it’s going to return something other than the current resource state.<p>Having said that, it’s not actually even clear if this is what it mandates, or if it really just means it must return the same HTTP status code as the original request. It says<p>&gt; <i>The resource server MUST respond with the result of the previously completed operation, success or an error.</i><p>It’s that “success or an error” bit. That could be read to mean “if the original result was success, the new one is success, otherwise the new one is the same error as the original”. But if you ignore that bit then the obvious interpretation of the sentence is the entire result payload must be the same. Though storing the data necessary to return the original payload could be prohibitively expensive if the payload includes some large regularly-modified resource.<p>I also wonder why this mandates returning the same error if the original request failed. If it failed with a transient error, why not allow the retry to attempt the request again? It would make sense if the draft said it MAY do this, but requiring it to preserve and return transient errors does not seem helpful.<p>And now that I’m on a roll, I also wonder about scenarios where the retry should error, such as authentication issues, but the original succeeded. If I send a request that succeeds, then my auth token gets invalidated, when I retry that request should it succeed again because of idempotency, or should it fail because of an auth error? I can see arguments both ways (it should succeed so the client knows its previous attempt worked, or it should fail because otherwise the client thinks it’s auth is valid).<p>And finally, I feel like a retried request that had previously been fully processed by the server should include a new response header indicating whether this is a cached response. This would help the client to make more intelligent decisions about the response (i.e. whether to believe it represents current state, or whether it may be outdated). I’m tempted to say it should include the Date value that was returned in the original response in this new header, so the client can see not only that it was a cached response but also how old it is.