11 ms·
The Idempotency-Key HTTP header field
- chrismorgan 5y agoI find the definition of idempotencyvalue in the grammar surprising: it looks like RFC 7230 quoted-string, but is actually just anything except for control characters, whitespace (!) and quotes, surrounded by quotes. Then I remember that the ETag header does the same thing since RFC 7232, where it used to use quoted-string with its escaping behaviour in RFC 2616. (And so they recommend avoiding backslashes because some recipients may mangle it.) Anyone have any idea why they’ve gone this way (ETag and Idempotency-Key), rather than using quoted-string? I will also note that people are already using a header named Idempotency-Key without quotes, e.g. https://stripe.com/docs/api/idempotent_requests https://stripe.com/docs/api/idempotent_requests. ETag has the “W/” indicator which requires some sort of disambiguation, but at least at this time I don’t feel Idempotency-Key needs quoting.
- chrismorgan 5y agoActually, for that matter, look through the examples listed of entities already using a header named Idempotency-Key, and all of them use unquoted values. Yandex Cloud and Worldpay say it must be a UUID (with their examples showing canonical textual representation), Adyen says it must not exceed 64 characters, the others don’t say anything about the value. All show UUIDs in canonical textual representation as their examples (well, Adyen actually prefixes it with UNIQUE-ID-, showing practically that it doesn’t have to be a UUID).
- zepto 5y ago“It does not matter if the operation is called only once, or 10s of times over. The result SHOULD be the same.” The result MUST be the same.
- jefftk 5y agoI think that's too strong: the response may have a component that is is non-deterministic. The important thing is that no matter how many times you call it the server state is the same.
- bastawhiz 5y agoAgreed. The state since the original success may have been mutated by another request since (or simply changed state as a result of any other async process), and the response may simply be a rendering of the latest server state. The response of the server absolutely should not be specified as being identical, since that's not how idempotent requests work. At that point, you're really just specifying a caching key for verbs that have side effects.
- sam0x17 5y agoYeah, it's more about there being no side effects after the first time than asserting anything about the actual response
- zepto 5y agoIf you distinguish the ‘response’ from the result, then I agree. Typically I think of the result as denoting the effect, and not the response message.
- jhayward 5y ago> The result MUST be the same. Transient errors happen, as well as loss of state errors, and a good protocol allows for that fact.
- Spivak 5y agoRequest 1: Status: OK Modified: True Request: 2 Status: OK Modified: False Request 3: Status: EAGAIN Modified: False Request 4: Status: TOOFAST Modified: False Request 5: Status: EACCESS Description: Your OAuth token has expired. Modified: False
- SvenL 5y agoI think this is due to side effect which are not “undoable”, like sending an e-mail. In case the timeout happen when the response is send, an email might be already send. If the request is send again another email is send. I think that’s why the RFC says “result” and not “state”.
- lazide 5y agoThen it is a fundamentally non-idempotent operation? In the case if an email you could use the idempotency key in the accounts outbox so you could detect if you’ve already sent the message and then no-op if that is the case, and you’re idempotent. The response must reflect something useful, which is probably going to be different in those two cases.
- skybrian 5y agoYes, writing status to log would be a better example; you might want to log retries.
- bhk 5y agoThe context is a paragraph describing a mathematical concept, not specifying the protocol. Any standardese imperative (SHOULD/MUST/...) is out of place here. It should read "The result is the same."
- mst 5y agoI suspect it's meant to include behaviours like this: https://news.ycombinator.com/item?id=27730372 https://news.ycombinator.com/item?id=27730372
- gigatexal 5y ago“ Idempotence is the property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application. It does not matter if the operation is called only once, or 10s of times over. The result SHOULD be the same.” Does not the use of “SHOULD” instead of “MUST” make this dead on arrival? Edit: I see a number of others have the same thoughts.
- pokoleo 5y agoIt's a bit funny to see an IETF draft for this! Adding idempotency support to Stripe's API was one of the things I built while an intern in 2015. We've since rewritten it almost entirely, but many the technical decisions made in 2015 still stand. One of the things that IETF doesn't specify ("an appropriate response") is that Stripe's Idempotency API has a response body has the latest rendering of the resource. Here's what I mean: # Set tax exempt status curl /v1/customers/cus_AJ6m5vWl7scnn6 \ -H "Idempotency-Key: aaaaaaaaaa" \ -d tax_exempt=reverse → {id: 'cus_AJ6m5vWl7scnn6', object: 'customer', tax_exempt: 'reverse', ...} # An unrelated request sets the customer's email curl /v1/customers/cus_AJ6m5vWl7scnn6 \ -H "Idempotency-Key: bbbbbbbbbb" \ -d email='foo@bar.com' → {id: 'cus_AJ6m5vWl7scnn6', object: 'customer', tax_exempt: 'reverse', email: 'foo@bar.com', ...} # Set tax exempt status with the first idempotency key: curl /v1/customers/cus_AJ6m5vWl7scnn6 \ -H "Idempotency-Key: aaaaaaaaaa" \ -d tax_exempt=reverse # The customer is re-rendered on the latest version → {id: 'cus_AJ6m5vWl7scnn6', object: 'customer', tax_exempt: 'reverse', email: 'foo@bar.com', ...}
- milofeynman 5y agoThat's very useful! I can't decide if the architecture is more complicated or simpler because of that. It helps avoid stale data showing up in the UI, etc. It seems like you just need to store the idempotency key and the request data (in case the data changes, to catch bad requests using same key...), but not the response. I think Amazon actually stores the response in a table for some amount of time (24 hours?), iirc https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/ https://aws.amazon.com/builders-library/making-retries-safe-... but I could be wrong.
- felixhuttmann 5y agoWhat I have always wondered about, in the stripe docs it says "Stripe's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors." which indicates that the idempotency functionality is created in a kind of layer around the main application functionality, and thus the request from the idempotency layer to the main app is not itself idempotent. So the idempotency key protects against faults on the network between the client and stripe's idempotency layer, but not against stripe-internal faults between the idempotency layer and the application. Is that the case? Why is the idempotency not achieved by using an idempotent database transaction or atomic operation? What is the value of responding repeatedly with a 500 if the original 500 was caused by a transient error? Adyen seems to similarly implement the idempotency in a separate data store (https://docs.adyen.com/development-resources/api-idempotency#designing-for-resilience https://docs.adyen.com/development-resources/api-idempotency...). Both stripe's and adyen's implementation seem to not treat transient faults within their own systems correctly.
- gbolcer 5y agoWhy don't they generate the key from the payload if it has to be unique and request specific?
- lanstin 5y agoYou might have two identical requests, say for two identical credit card purchases, or you might have faulty retry on the same request.
- hit8run 5y agoMaybe because the client should define what is the payload he wants to treat as idempotent. A request with the same message might have the same payload hash but it is sent on purpose twice.
- jmull 5y agoThat’s not it… this RFC requires that the server know how to distinguish two requests with different payloads but the same idempotency-key value (and return a 422 response in that case). Not to mention, it makes little sense for a server to be able to implement idempotency without understanding the idempotency semantics of the payloads it accepts.
- brandur 5y agoYour parent is correct. Think of a simplified example of posting a $1 charge to a customer. POST /v1/charges `{amount: 100, currency: usd, customer: 123}` You might do that, and then later charge them another $1: POST /v1/charges `{amount: 100, currency: usd, customer: 123}` The request payload would be identical, so the API can't use just that to distinguish requests. Adding an `Idempotency-Key` lets you tell the server that these are purposely two independent charges. > this RFC requires that the server know how to distinguish two requests with different payloads but the same idempotency-key value (and return a 422 response in that case). This is an error checking facility to make sure that the idempotency keys are being used correctly. Sending a different request with the same idempotency key is non-sensical, so the server tells its client about the problem.
- shawnz 5y agoSeems like kind of a wordy name, why not just "nonce"?
- topogios 5y agoI think nonces are generally thought of as numbers, and as a client it might be simplest in some cases to be able to reuse or derive from an existing non-number key.
- chrismorgan 5y agoThe HTML nonce attribute is a string: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce https://developer.mozilla.org/en-US/docs/Web/HTML/Global_att...
- SideburnsOfDoom 5y agoNot recommended to use "nonce" casually in the UK. Urban Dictionary will tell you why.
- shawnz 5y agoIMO that ship has sailed given the word has been extensively used in software contexts for some time.
- SideburnsOfDoom 5y agoIt's still somewhat a specialised word, even in software contexts. Or at least, UK people prefer not to to use it.
- detaro 5y agoIt probably makes some sense to reserve "nonce" for security/cryptographic use.
- vishnugupta 5y agoI'm gland for this much needed change. I hope it also makes it to frameworks and libraries such as JBoss, ExpressJS. Idempotency is simple to understand but tricky to implement in practice because of a bunch of edge cases; handling of business failures, response (should it be the first successful response?), how to document the behaviour without confusing the developers and so on. So developers either don't consider it at all or when they do, they forget to consider all these aspect. FWIW we, as a team, spent quite some time debating and going back and forth; I'm happy with the final behaviour we settled on though the documentation could have been better[1] [1] https://developer.uber.com/docs/payments/glossary https://developer.uber.com/docs/payments/glossary
- jdnier 5y agoI see an interesting application for the Validity, Expiry, Enforcement, Fingerprint sections. Many web apps generate HTML forms but submit form values via an API endpoint. With browser web tools and standard options like "copy-as-curl", it's very easy to run a "replay attack", where an adversary submits the form manually once, does a copy-as-curl (or similar) on that POST, then replays the POST repeatedly, updating particular values in the generated curl output for each subsequent POST. This gets around form protections like captcha and allows for rapid abuse via the API that backs the form. Enforcing that an idempotency key/token be generated on the server side or that it match the submitted content or be valid for a short timespan could make replay attacks less convenient.
- DangitBobby 5y agoIs this protection not already baked into the CSRF token?
- Sayrus 5y agoThat and also, most captcha I've used so far require a server-side validation that is not replayable with Curl (as the token has been used during the first submission).
- jdnier 5y agoYes, but captcha is on the form. I'm thinking more about a single-page app that submits form data via an API. That API call can generally be replayed.
- zemnmez 5y agoNo, a CSRF token only introduces information that is not part of the ambient authority of the HTTP client (i.e. an attacker cannot implicitly use it) – it is not uncommon to have deterministic or relatively constant CSRF tokens (e.g. the double-send cookie method). An n-once would fulfil your criteria but is importantly not a valid CSRF token unless it is also correlated or derived from something the attacker can’t know like a session; otherwise the attacker can use their own n-once to submit a victim request.
- vp8989 5y agoIt's more appropriate IMO to name it something like "Request-Identifier". All the client should indicate is that if you get 2 or more POSTs with that same Id, you are free to no-op on any after the 1st successfully handled one. Idempotency is an emergent property of a system so it doesn't make sense that a client would dictate the key that's used to provide that behavior. So if the Idempotency-Key is quite likely not to be the actual "Idempotency-Key" in any sufficiently complex system, then don't name it that.
- joshribakoff 5y agoYes I have seen idempotency keys generated on the client that were comprised of the date and amount of money used to make a payment. Don’t do this. Just use a randomly generated request ID when the request hits the API. The idempotency key is (usually) there to prevent things like an RPC or event (in the backend) being retried causing duplicate side effects. Presumably you still want users to be able to intentionally submit two payments for the same amount on the same date (csrf tokens are more appropriate to prevent accidental duplicate submission)
- karmakaze 5y agoI want both. If there are two network requests for the same action, I want to be able to trace them distinctly and also know that they are doing one thing.
- mercantile 5y agoExactly this. Multiple requests with the same idempotency key are still different requests, and you want to be able to track them independently. Also worth noting that a header named 'Request-Id' is already a widespread convention. You'll see one back from many popular APIs like AWS or Stripe, and definitely want a name for the idempotency header that differentiates itself from that.
- vp8989 5y agoThey are 2 distinct concepts for sure, but if you also need to track each request independently then it would seem more robust to generate a separate Id for that from within the scope of your system. I don't think you would want to rely on a client to differentiate "physical" requests for you. Maybe "Logical-Request-Identifier" and "Physical-Request-Identifier"?
- unilynx 5y agoThis (partly) solves some cases of the two generals problems, where you didn't receive a response to eg. a resource creation request but aren't sure whether that means that you can safely retry it, or need to use other APIs to figure out the ID of the created resource, if it exists Some AWS APIs have it, eg https://docs.aws.amazon.com/medialive/latest/apireference/inputs.html#inputs-prop-createinput-requestid https://docs.aws.amazon.com/medialive/latest/apireference/in... - I wish all their creation APIs did
- 0xbadcafebee 5y agoIt's so funny to watch REST get "patched" with headers rather than just update the protocol. Path of least resistance I guess
- tptacek 5y agoI'm not sure I understand why this needs to be standardized. Is there something that middleboxes and CDNs need to do with messages marked idempotent? Would a standard header enable browsers to do something new that they're all likely to actually do? Otherwise: HTTP already specifies a bag-of-attributes header system, and this is just an application of it. Why is it in the HTTP standards?
- chalst 5y agoThis is potentially of interest to any application making use of POST. Its generality and simplicity justifies standardisation.
- tptacek 5y agoThe concept is worth knowing about, but that doesn’t mean it belongs in the standard, especially since there’s more than one way to do it. I’m wondering if someone knows a particular reason why this way needed to be standardized.
- mst 5y ago"Providing one solid way to do it to act as a co-ordination point" seems like a reason that could at least be argued, but without asking the authors I have no more insight than that, sorry.
- grishka 5y agoA real-world example from my previous job. You have a chat in your mobile app. Messages are sent using HTTP requests, and received using HTTP long polling. Now imagine sending a message over a slow network while on a departing subway train (service is only at stations). TCP & SSL are established successfully, then the request itself is sent, but you leave the network coverage before you receive the response. So you have no idea whether the message was actually sent. When you reconnect at the next station, you receive a message over long poll, but — because the request failed as far as you're concerned — you have no idea whether it's the message you sent. To resolve this, you need to have the ability to ask the server for a response to a previous request, but without actually performing that request a second time. Or, alternatively in this particular case, you need the server to accept a unique client-generated ID in the request and return it to you over long poll.
- est31 5y agoIt's interesting that this standardization effort hasn't happened earlier, because it seems such an obvious feature addition to POST requests. HTTP is decades old after all, and nobody thought about this prior to the payment processors? I guess nobody really cares if you have two posts in a forum with the same content, but if you do two payments it's way worse. After all, double spend prevention is what bitcoin does its hugely expensive proof of work for.
- kyrra 5y agoGoogler, opinions are my own. I work in payment and idempotency is always a discussion point. This draft links to one of our docs (though the draft points to a 404 URL, the correct link being[0]). As the draft calls out, Google Standard Payments uses the "requestId" field as our idempontency key, which is part of the request body, rather than in the HTTP header. We did this specifically to decouple the protocol from the behavior of the request. We could take the existing definitions and put that payload into any other protocol and it would work without having to use that protocol's sidechannel data (aka, the HTTP header). Our design makes idempontency part of the application layer, rather than any middlebox or load balancer. [0] https://developers.google.com/standard-payments/guides/connectivity/protocol-standards#request_idempotency https://developers.google.com/standard-payments/guides/conne...
- herodoturtle 5y agoThanks for the insightful comment; makes good sense. Could you kindly share your view on the security implications of this approach - in particular with reference to the security context outlined in section 5 of the IETF draft: > For idempotent request handling, the resources MAY make use of the value in the idempotency key to look up a cache or a persistent store for duplicate requests matching the key. If the resource does not validate the value of the idempotency key prior to performing such a lookup, it MAY lead to various forms of security attacks and compromise.
- nivertech 5y agoYes, that's the case if you use it for unauthenticated users or public API calls. For that reason I do not support idempotent retries for public API calls. For the authenitcated users, you cache/store the idempotency keys scoped by the currently authenticated user, i.e: {user_id, idempotency_key} You can add more parts to thie key for better security, i.e.: {user_id, api_call_name, idempotency_key} or even {user_id, api_call_name, input_args_hash, idempotency_key} etc.
- hit8run 5y agoInteresting and I totally get your point. What protocols do you support besides HTTP?
- jmull 5y agoI don’t get it. For a particular request, a server must implement its documented idempotency guarantee, and the client needs to understand the server’s guarantee to know whether it’s safe to retry. How does this header help or change anything? It’s only real use (that I see, please correct my misunderstanding if there is one) is to paper over an incorrect API design, where you want idempotent behavior but can have identical payloads for distinct requests. (e.g., imagine a chat app, where the message being sent is the POST request body, and there’s no other metadata about the message. In that case, there’s no way to distinguish a new “you up?” message from a retry. However, such an API should simply have a message id value sent with each message.)
- hcarvalhoalves 5y ago> Let's say a client of an HTTP API wants to create (or update) a resource using a "POST" method. Since "POST" is NOT an idempotent method (…) Use PUT instead? The deterministic key that would go in the Header goes as part of the URI. I’m not seeing why standardize a roundabout way of doing the same. Am I missing something?
- p4bl0 5y agoYes, that was my thought too. The HTTP verb PUT is specifically made for idempotency, why would HTTP need a header filed for that?
- bpicolo 5y agoBecause the use case isn't necessarily modifying a resource. Charging somebody for a product, for example, doesn't have natural idempotency. They could buy the same item twice
- deleted 5y ago[deleted]
- p4bl0 5y agoIsn't that a modeling problem? Let's say you don't pay for an item but for a basket even if it has only one item. If each specific basket has its own unique id then you have a unique resource that can have a paid or not yet paid status, and use HTTP verbs appropriately against it (e.g., POST to add an item to the basket, or PUT to pay for the basket). Another basket, even with the same item(s) added to it, would have another id. Problem solved.
- bpicolo 5y agoFor the case of this header, you're interacting with third parties that don't speak your application domain. That "unique id" you mention is exactly the use case for the idempotency key this RFC proposes. You can model your unique basket identifier in your application domain, and use that identifier as the idempotency key in interactions with third parties. This is useful mostly because networks and applications are not necessarily reliable.
- the_arun 5y agoPlease note that idempotency key is not specific to just HTTP requests - we may have to implement this for async use cases as well - eg. events streams & messages.
- lilyball 5y agoThe “Concurrent Request” part concerns me. Just because the server thinks the original request is still going on doesn’t mean the client does. Example: Client issues a request with a 10 second timeout. Network conditions are such that the request doesn’t get fully sent until 9.9 seconds have passed (at which point network conditions have cleared and are fast). Client gets a timeout, immediate retries. From the client’s perspective, there’s no concurrent request. What the server sees is a request followed 0.1 seconds by an identical request. It naturally says “I’m not done with the first, the second is a concurrent request” and sends the required error. Net result is the server has applied the request but the client is left with an error. The client must now send a third identical request just to find out the actual results. Ultimately, the problem boils down to the fact that the client and server do not necessarily have the same idea of what requests are currently in-flight. And yet this draft declares that the server MUST return an error if it thinks the request is still being processed.
- polynox 5y agoYou are right that this is a scenario. I imagine that a permissible solution could be to effectively join the requests together by waiting for the (original) request to be finished.
- lilyball 5y agoThat seems like the obvious behavior, but this draft says the server MUST return a conflict error, which means this behavior is not permissible.
- lilyball 5y agoQuestion: 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. 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 > The resource server MUST respond with the result of the previously completed operation, success or an error. 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. 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. 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). 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.
- johnday 5y agoI think you have misunderstood slightly. GET, for example, is an idempotent method [1], which means "the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request." However, it is NOT true that sending the same GET request at different points in time would have the same effect - if a resource is deleted or moved, you might get a 404, 301 or 200 where previously you got something else. When idempotence is talked about in these RFCs there's an implied caveat that the "multiple requests" they talk about happen at the same time, under the same network conditions. I think that's what they mean by "identical". [1] https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2 https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2
- xupybd 5y agoHow are these RFCs written? I love the formatting is there a tool chain around these?
- iand 5y agoYes, see here https://www.rfc-editor.org/pubprocess/tools/ https://www.rfc-editor.org/pubprocess/tools/
- thayne 5y ago> If there is an attempt to reuse an idempotency key with a different request payload, the resource server MUST reply with a HTTP "422" MUST seems too strong here to me. For some applications it's probably sufficient to treat this case the same as if the payload was the same, and it requires the server to persist either the original payload, or a hash thereof. And what if the payloads differ only by a timestamp, or a randomly generated id, etc.?
- tremoloqui 5y agoThis seems to be missing or at least conflating the meaning of idempotence. The draft correctly identifies idempotence as a "property of certain operations", but what the draft seems to describe is locking and caching. Locking and caching are important to building idempotent operations, but shouldn't be conflated with idempotence which is a conceptual property of the operation. I like what the draft describes, but it would be better done in the correct context.