jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: clarify that quota policies are unique in policy . 
 If server defines two policies , e.g. and the response header contains , How do I know if I can make 2 more requests , or download 2 more bytes ? Is having multiple policies with different quota units not allowed ? 
 Good catch ! The list items MUST be unique . I will specify this for now .  about switching  to a Dictionary ? This requires some tweak though e.g. prefixing the units with . cc : 
 I 'd use a short name for the policy , so that it could be referred to separately ; e.g. ,
Paragraph (version A):
The field is a non-empty List of Items.  Each item is a quota-policy.
Paragraph (version B):
The field is a non-empty List of Items.  Each item is a quota-policy.
Two quota policies MUST NOT be associated with the same quota units
value.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: suggestion on server behavior . Thx ! - 
 In section 4 it says , In section 4.1 it says , These statements seem contradictory . I do not see how we can declare as REQUIRED considering many APIs do not and will not implement these headers . It seems to me that if a client receives a header they can choose to either count the requests they make within the time window or they can monitor the . With neither of those values it would be difficult to do something useful . How would you feel about words like this : 
 we are open to clarifications . The rationale for the current behavior is in I think RateLimit - Reset is always REQUIRED . 
 In theory someone could use RateLimit - Limit to provide a limited number of " free " requests as a trial for their API . They may not choose to have a reset window and just require payment before allocating more calls . This is a bit of an edge case use of the headers , but might be just enough of a justification to limit constraints that we add . Having said this , I still do n't understand how we can make any of these headers required considering there are so many existing APIs that do n't return these headers today . How does a developer decide if they MUST return these headers for their API ? Assuming the " free trial " scenario is not considered a valid scenario for this header , then how would you feel about these words ? 
 SGTM .
Paragraph (version A):
A server uses the RateLimit header fields to communicate its quota
policies.  Sending the RateLimit-Limit and RateLimit-Reset header
fields is REQUIRED; sending RateLimit-Remaining header field is
RECOMMENDED.
Paragraph (version B):
A server uses the RateLimit header fields to communicate its quota
policies.  A response that includes the RateLimit-Limit header field
MUST also include the RateLimit-Reset.  It MAY also include a
RateLimit-Remaining header field.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: See 
 feel free to merge if ok 
 LGTM
Paragraph (version A):
Discussion of this draft takes place on the HTTPAPI working group
mailing list (httpapi@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/browse/httpapi/ [1].
Paragraph (version A):
The source code and issues list for this draft can be found at
https://github.com/ietf-wg-httpapi/ratelimit-headers [2].
Paragraph (version A):
IANA is requested to create a new registry to be called "Hypertext
Transfer Protocol (HTTP) RateLimit Parameters Registry", to be
located at https://www.iana.org/assignments/http-ratelimit-parameters
[3].  Registration is done on the advice of a Designated Expert,
appointed by the IESG or their delegate.  All entries are
Specification Required (IANA, Section 4.6).
Paragraph (version B):
IANA is requested to create a new registry to be called "Hypertext
Transfer Protocol (HTTP) RateLimit Parameters Registry", to be
located at https://www.iana.org/assignments/http-ratelimit-parameters
[1].  Registration is done on the advice of a Designated Expert,
appointed by the IESG or their delegate.  All entries are
Specification Required (IANA, Section 4.6).
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: clarify that we return only the values related to the quota policy identified by the expiring - limit 
 If there are multiple policies in effect , which is reflected in these fields ? RateLimit - Limit has advice about this , but these do not . 
 Ok , we should clearly state that all the three basic fields return the values associated to the expiring - limit .
Paragraph (version A):
The "RateLimit-Remaining" field response field indicates the
remaining quota units defined in service-limit associated with the
client.
Paragraph (version B):
The "RateLimit-Remaining" response field indicates the remaining
quota units associated to the expiring-limit.
Paragraph (version A):
The "RateLimit-Reset" field response field indicates the number of
seconds until the quota resets.
Paragraph (version B):
The "RateLimit-Reset" field response field indicates the number of
seconds until the quota associated to the expiring-limit resets.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: Parameters are not allowed , and if they appear they MUST be ignored . 
 Why not just ' If Parameters appear they MUST be ignored ' ? 
 we wanted to stress the fact that servers are not expected to provide parameters , otherwise some clients could just consider the whole field value malformed and ignore it . 
 The normal way to do that is something like : 
 Ok , I 'll rebase this PR tomorrow :) Late night now in Italy . Thanks for all this support :) 
 In a few places , the specification says " Parameters are not allowed " but does not spell out what should happen if they appear .
Paragraph (version A):
The field is an Item and its value is a non-negative Integer referred
to as the "expiring-limit".  Parameters are not allowed.
Paragraph (version B):
The field is an Item and its value is a non-negative Integer referred
to as the "expiring-limit".  This specification does not define
Parameters for this field.  If they appear, they MUST be ignored.
Paragraph (version A):
The field is an Item and its value is a non-negative Integer
expressed in service-limit.  Parameters are not allowed.
Paragraph (version B):
The field is an Item and its value is a non-negative Integer
expressed in service-limit.  This specification does not define
Parameters for this field.  If they appear, they MUST be ignored.
Paragraph (version B):
This specification does not define Parameters for this field.  If
they appear, they MUST be ignored.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: This should be specified without resorting to a metaphor that some may find confusing . 
 I 'm ok to removing this line .
Paragraph (version A):
A low RateLimit-Remaining field value is like a yellow traffic-light
for either the number of requests issued in the time window or the
request throughput: the red light may arrive suddenly (see providing-
ratelimit-fields).
Paragraph (version B):
When the value of RateLimit-Remaining is low, it indicates that the
server may soon throttle the client (see providing-ratelimit-fields).
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: It would be better to say that rate limiting information in what we used to call non - firsthand responses ( basically , anything with an Age header ) should be ignored . 
 Is the following text ok ? 
 Looks good , just a few suggested tweaks :
Paragraph (version A):
As is the ordinary case for HTTP caching (HTTP-CACHING), a response
with RateLimit fields might be cached and re-used for subsequent
requests.  A cached response containing RateLimit fields does not
modify quota counters but could contain stale information.  Clients
interested in determining the freshness of the RateLimit fields could
rely on fields such as the Date header field and on the time window
of a quota policy.
Paragraph (version B):
HTTP-CACHING defines how responses can be stored and reused for
subsequent requests, including those with RateLimit fields.  Because
the information in RateLimit fields on a cached response may not be
current, they SHOULD be ignored on responses that come from cache
(i.e., those with a positive current_age; see Section 4.2.3 of HTTP-
CACHING).
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: It would be better for interoperability if they MUST be ignored .
Paragraph (version A):
Malformed RateLimit fields MAY be ignored.
Paragraph (version B):
Malformed RateLimit fields MUST be ignored.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: RFC6973 Section 5.2.1 would be a better reference . 
 Ok , thanks
Paragraph (version A):
Clients that act upon a request to rate limit are potentially re-
identifiable (see Section 7.1 of DNS-PRIVACY) because they react to
information that might only be given to them.  Note that this might
apply to other fields too (e.g.  Retry-After).
Paragraph (version B):
Clients that act upon a request to rate limit are potentially re-
identifiable (see Section 5.2.1 of PRIVACY) because they react to
information that might only be given to them.  Note that this might
apply to other fields too (e.g.  Retry-After).
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: See . 
 iirc there was a discussion on stuff . In general I 'm ok with just do you see any issue with that ? 
 No issue , I was aware of the BCP and I think this case fits the first provision for segregating the name spaces in the Appendix B , so any one of the proposed solutions there , including yours , is fine with me .
Paragraph (version A):
To avoid clashes, implementers SHOULD prefix unregistered parameters
with an "x-<vendor>" identifier, e.g. "x-acme-policy", "x-acme-
burst".  While it is useful to define a clear syntax and semantics
even for custom parameters, it is important to note that user agents
are not required to process quota policy information.
Paragraph (version B):
To avoid clashes, implementers SHOULD prefix unregistered parameters
with a vendor identifier, e.g. "acme-policy", "acme-burst".  While it
is useful to define a clear syntax and semantics even for custom
parameters, it is important to note that user agents are not required
to process quota policy information.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: Clarifies that Without w a quota - policy is meaningless , so it 's just a clarification . 
 Oops , this should have been explicit since day 1 ! Good catch !
Paragraph (version A):
The "w" parameter specifies a time window.  Its syntax is a "time-
window" defined in time-window.
Paragraph (version B):
The REQUIRED "w" parameter specifies a time window.  Its syntax is
a "time-window" defined in time-window.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: clarify that quota - policy examples are not field values . 
 To clarify that examples in service - quota are not field - values
Paragraph (version A):
where quota-units is a non-negative sf-integer.
Paragraph (version B):
where "quota-units" is a non-negative sf-integer.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: consistent use of in document name cc : 
 Consistently use " fields " instead of " headers " since can be used in trailers .
Paragraph (version A):
Simplify API documentation by eliminating the need to include
detailed quota limits and related header fields in API
documentation.
Paragraph (version B):
Simplify API documentation by eliminating the need to include
detailed quota limits and related fields in API documentation.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: reformats goals 
 to reorganize Goals section with a single type of list 
 Single type of list as in using the same list styling for goals and non - goals ? Or leaving just the list of goals and use prose for non - goals ?
Paragraph (version A):
limited to 1000 request per hour.
Paragraph (version A):
Moreover system metrics, statistics and heuristics can be used to
implement more complex policies, where the number of acceptable
request and the time window are computed dynamically.
Paragraph (version B):
limited to 1000 requests per hour.
Paragraph (version B):
Moreover system metrics, statistics and heuristics can be used to
implement more complex policies, where the number of acceptable
requests and the time window are computed dynamically.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: Hi The link to the mailing archive ( ) is 404 . I assume the correct link is : 
 Hi thanks for the report , should be fixed soon .
Paragraph (version A):
Discussion of this draft takes place on the HTTP working group
mailing list (httpapi@ietf.org), which is archived at
https://lists.w3.org/Archives/Public/ietf-httpapi-wg/ [1].
Paragraph (version B):
Discussion of this draft takes place on the HTTP working group
mailing list (httpapi@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/browse/httpapi/ [1].
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: Improves example description 
 https://ietf - wg- The example with just RateLimit - Limit and RateLimit - Reset In it seems this is a case where the RateLimit - Reset value is not able to be used to determine how long one should wait , but is rather just a Limit definition ? Why not then just use RateLimit - Limit : 10;w=1 and omit the other two headers ? Is this to cater for the inevitable 429 to provide a RateLimit - Reset value at that point ? If that is the case I question the value of using the two headers in “ successful ” responses . 
 This example is related to an implementation that uses the " old " ratelimit field set , that do not support . We should improve the description . 
 : +1 :
Paragraph (version A):
The server does not expose "RateLimit-Remaining" values, but resets
the limit counter every second.
Paragraph (version B):
The server does not expose "RateLimit-Remaining" values (for example,
because the underlying counters are not available).  Instead, it
resets the limit counter every second.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: clarifies interaxtions with 3xx 
 Note that here we clash with the scope of these fields . Do they refer to the current request which for whatever reason ends up in a redirection or do they refer to the request that will follow up to the target location ? We have been careful to always talk about the current request and leave the scope undefined but one way or another contained in this request ( ie . the same service , the same path prefix , the same domain , the same hour , or any other criteria that can emerge from the fact we are performing this particular request ) . With the fields applied to the follow up redirection this could change , because the target location could be any URL . So what would happen if we really wanted to limit the endpoint that causes the redirection instead of the target location ? A point can be made about these values being of no use when an endpoint is redirected , but if the redirection was conditional or temporary , we 'd lose the ability to convey these limits . In addition , a redirect might target a different service altogether , potentially with its own policies this service might know nothing about . I think giving a different meaning to these values in the case of redirection creates an exception that does not carry enough weight . In the general case where a redirection is permanent , you can simply assume as a client that you need to call at least once the target location in order to obtain rate limiting information . After all , your request was serviced , not refused , so if the target was under the control of this service and it determined that you have no quota , it could just as well refuse to respond with the redirect and instead send back a 429 or some other client error status rather than waiting for you to perform another request only to then refuse to service it . 
 I tried to be non - normative , and just warn implementers - both client and server - to be carefull when 3xx and I avoided providing details ( eg . whether is on the same service or not ) . But I think you can provide a better wording : if you think this should be placed elsewhere ( eg . Security considerations ) feel free to do it ! : rocket : 
 PTAL :) 
 I think providing a reminder to the server implementer that if you are going to return a redirect and you know it is to the same API , then it would unwise to return a 0 in the RateLimit - Remaining . This feels like a valuable reminder to me . 
 No Correct Probably we should warn that returning a with 30x could refrain clients to make a request , but I wo n't be normative on that cc : 
 See We need to provide guidance in redirection cases , probably .
Paragraph (version B):
Servers should be careful in returning "RateLimit" fields in
redirection responses (eg. 3xx status codes) because a low
"RateLimit-Remaining" value could limit the client from issuing
requests.  For example, given the rate limiting fields below, a
client could decide to wait 10 seconds before following the
"Location" header, because "RateLimit-Remaining" is 0.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: specific throttling behavior is out of scope FAQ 8 integrated in RateLimit - Remaining and Receiving Ratelimit fields 
 We used the Limit and Remain values in one of our client applications that was migrated from a legacy SOAP service to our REST based API in order to ensure we never get a 429 response ( this is because the legacy code could not gracefully retry requests without major refactoring ) . When we get to 80 % of quota ( 20 % Remain ) we start respecting the value in the Reset header . In section 7 you touched on a concept ‘ A client SHOULD NOT exceed the " quota - units " expressed in " RateLimit - Remaining " before the " time - window " expressed in " RateLimit - Reset " . ’ We do n't want to mandate a strict behavior on client , but we can surely add this sentence as an example behavior . The current spec allows comments , so you can already do it . The spec allows to address this use - case transparently , by artificially lowering the values provided in the fields . 
 We should probably integrate and remove since it 's already in the spec . 
 This is something I quickly commented on but the alternative of dynamically modifying the values as the rate saturates is fairly reasonable , so those informational parameters might as well be part of an extension document .
Paragraph (version A):
Clients MUST NOT assume that a positive "RateLimit-Remaining" value
is a guarantee of being served.
Paragraph (version A):
A low "RateLimit-Remaining" value is like a yellow traffic-light: the
red light may arrive suddenly.
Paragraph (version B):
Clients MUST NOT assume that a positive "RateLimit-Remaining" value
is a guarantee that further requests will be served.
Paragraph (version B):
A low "RateLimit-Remaining" value is like a yellow traffic-light for
either the number of requests issued in the "time-window" or the
request throughput: the red light may arrive suddenly (see providing-
ratelimit-fields).
Paragraph (version B):
consuming all the quota according to the exposed limits and then
wait.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: fixes typos , improve flow
Paragraph (version A):
As is the ordinary case for HTTP caching (RFC7234), a response with
RateLimit fields might be cached and re-used for subsequent requests.
A cached RateLimit response, does not modify quota counters but could
contain stale information.  Clients interested in determining the
freshness of the RateLimit fields could rely on fields such as "Date"
and on the "window" value of a "quota-policy".
Paragraph (version B):
As is the ordinary case for HTTP caching (RFC7234), a response with
RateLimit fields might be cached and re-used for subsequent requests.
A cached "RateLimit" response does not modify quota counters but
could contain stale information.  Clients interested in determining
the freshness of the "RateLimit" fields could rely on fields such as
"Date" and on the "time-window" of a "quota-policy".
Paragraph (version A):
The value of "RateLimit-Reset" is generated at response time: a
client aware of a significant network latency MAY behave accordingly
and use other information (eg. the "Date" response field, or
otherwise gathered metrics) to better estimate the "RateLimit-Reset"
moment intended by the server.
Paragraph (version B):
The value of "RateLimit-Reset" is generated at response time: a
client aware of a significant network latency MAY behave accordingly
and use other information (eg. the "Date" response header field, or
otherwise gathered metrics) to better estimate the "RateLimit-Reset"
moment intended by the server.
Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: servers are not forced to always return ratelimit fields clients must not assume the presence of ratelimit fields performance hints for providers 
 Waiting for then :) 
 PTAL :) 
 Looks great to me . The intent is nice and clear . 
 The spec to define header inter - dependencies and returning policies [ x ] Limit -Reset [ x ] Limit , Remaining , Reset Do I have to always return all headers ? No Do I have to expose all headers or I can only expose a subset ? Limit , Reset are REQUIRED ,  is OPTIONAL Do we need to add some considerations on client implementation ? Already present . 
 clarifies that clients MUST NOT assume a server always returns fields 
 Comment by  . In https://ietf - wg- You state ‘ A server MAY use one or more " RateLimit " response fields defined in this document to communicate its quota policies . ’ but it does not clearly define how they would be used in isolation or how a client should respond to a limited set of headers ( other than discussed earlier above ) My feeling is RateLimit - Limit can be optional and RateLimit - Remaining and RateLimit - Reset can be used as a pair . RateLimit - Reset would only have value in isolation if sent with a 429 response code , on other responses it would be meaningless . 
 It could also make sense to return Reset with other status codes such as and , so I think we do n't really want to mandate a specific relation other than , at most , saying that unsuccessful requests ( for a broad definition of those , possibly including and at a minimum ) with this field are expected to be unsuccessful until that time elapses . 
 After a couple of years of adoption , my experience is the following : use all 3 fields . Though theoretically one could just return and , I never found an implementation doing this : heavycheckmark : do n't know Remaining , and just return Limit and Reset with a fixed window ( eg . 1 second ) . We can then recommend the following : Limit , Reset : MUST Remaining : SHOULD Since https://ietf - wg- I now think that we should n't mess with status codes . if this sounds reasonable to you , I can provide a PR 
 Yes , it sounds good , thank you ! 
 Looks good !
Paragraph (version B):
Servers are not required to return "RateLimit" fields in every
response, and clients need to take this into account.  For example,
an implementer concerned with performance might provide "RateLimit"
fields only when a given quota is going to expire.
Paragraph (version B):
Implementers concerned with response fields' size, might take into
account their ratio with respect to the payload data, or use header-
compression http features such as HPACK.
Paragraph (version B):
A client receiving "RateLimit" fields MUST NOT assume that subsequent
responses contain the same "RateLimit" fields, or any "RateLimit"
fields at all.