Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: a server SHOULD be configurable so that it can provide with or without compliant clients have to use SFV parsers non - compliant / pre - existing clients can still process fields with quota - policy : off and be migrated in time . eg .. 
 to support lightweight / IoI devices , it 's auspicable to always support the simple version :P 
 This document strives to formalize behavior that a lot of existing servers and clients already implement , i.e. the " 3 - integer ( Limit / Remaining / Reset ) " model of ratelimit HTTP headers . If existing clients already parse in some or all circumstances , is n't changing from an integer to a SFV list of integers a backwards - incompatible change ? Of course , there 's an upgrade path possible for existing clients : they should parse up to the first ( if any ) if they want to support both " old"-style and the in this RFC . But an upgrade path is not the same thing as backwards compatibility . In , suggests the following as behavior an interoperable client could implement : It 's precisely clients like this that would be affected by a change from integer - only to a SFV . Should we not call out that we are breaking compatibility with the de - facto standard in the wild ? 
 While this is worth clarifying , the pseudocode is not a complete implementation , because the spec requires the field values to be validated before use . Eg . 
 I think the usage of SFV is orthogonal to our idea of backwards compatibility regarding this information . Of course many if not all existing clients will need to parse these headers differently because of this , but that is also the case with many of them parsing only the prefixed headers , or those that have slight variations in the names . The important thing is that once this parsing step is completed they should have at least the same basic information they used to have without the need to modify their rate limiting logic if they do n't want to . 
 I think it 's worth calling out any change developers need to make to their parsing logic . That 's considerably more difficult to change than just altering what headers to look for . Parsing a SFV header is non - trivial , especially compared to parsing an integer . I 'm not pushing in this PR for any changes to the spec , aside for a clarifying note about what it takes to upgrade to this spec . 
 sure , that 's something to be aware of -- that said , I 'd expect implementors to limit the changes to replacing the logic of a header parsing step with that from a SFV parsing library and end up with the same information - there are plenty such libraries out there by now . :) 
 If we have expectations for what implementors will do , those should typically be written in the document . :) 
  , but ... is n't that fully implied by specifying the fields follow the SFV RFC ? 
 Related to . can clarify / fix this ? 
 PR replaced with 
 This is still a suggestion I have n't had enough time to really think through , but I thought it might be worth discussing . The document currently says that for Limit , the server can give back a list of all of the quota policies currently " in force " . But for Remaining and Reset , the server can only give back ( without resorting to nonstandard extensions ) those values for the policies with the least remaining quota . It seems like it would be more " consistent " to instead have : and Reset both have a similar syntax to Limit , where you can give a list with w= parameters . ( This is what I 'm getting at in . ) Or , works like Remaining and Reset , where you only talk about the policy with the least remaining quota . We could still keep the w= parameter , just no list . This is what I 'm proposing here . From talking offline , it seems the intention is that only the first value of Limit is actionable ; the rest is just informative . I question whether we want to put information that is n't machine - actionable in an HTTP header / trailer . So what if we took and made it be a single SFV item , instead of a list of items ? In the simplest case , this changes nothing . is equivalent either way . So the document would still be backwards compatible with most of what 's out there , modulo the header name . would become just . Obviously , the case that needs refactoring is something like : Servers could either only mention the lowest window , or they could declare their other windows with a parameter ? If we want to keep the informative notion of multiple windows standardized , we can even standardize the name and format of this parameter . Here 's one possible idea : 
 We thought about it , but we decided to retain the current format to always have the three integers as mandatory actionable content . This avoids unnecessary complications for the average users while allowing advanced users to process fields with SFV using the first value as the key for the quota policy . The point is that we do not forbid to process the quota - policy , but we want that clients are not forced to do so . Does it make sense to you ? Is there an use case not covered by the current setup ? 
 Are you saying that you want the spec to be usable even if someone does n't want to implement SFV ? If so , how would you have people do that ? By saying that clients can only parse up to the first character , if they do n't want to validate SFV data ? If so , I think this language may be a problem : By saying that is a list , but that implementations can ignore things past the first , I think the document would basically be saying that parse errors after can be silently dropped , and the data before the can be understood anyway . I 'm pretty sure the SFV folks would object to that . From reading and implementing SFV , I get the strong sentiment that it is an all - or - nothing sort of spec . You need to buy into the fact that it dictates how parsing happens ( and that implementations need to use an SFV library ) , or you need to give up using it entirely . 
 In https://ietf - wg- we state that they may be ignored wrt the client behavior , without mentioning the parsing . About being able to treat a field as a non - structured field , this can be useful to the discussion 
 According to this  's comment it 's better to stick to SF , so the original point of stays . when parsing quota - policies To ease the transition from old implementations , I would just suggest then that ratelimit providers SHOULD support a flag to enable / disable the providing of service - quota information . 
 If you want to weaken it further , you could say " MAY wish to provide " I do n't know how widespread the transition would need to be nor how long . It 's up to you .
Paragraph (version B):
To ease the migration from existing rate limit headers, a server
SHOULD be able to provide the "RateLimit-Limit" field even without
the optional "quota-policy" section.