Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: Improves terminology replacing with . cc : 
 It seems in the context of this design limit and quota terminology mean the same thing , however the header name to represent quota is RateLimit - Limit , which stutters . Would RateLimit - Quota not be better because it seems to mean the same thing and avoids stuttering ? 
 Well , conveys the , which is expressed in terms of . The name makes me think more to a than to or . Since implementers already use , with we decided not to change field names . WDYT to rename instead ? 
 One potential issue with is that the quota can be not directly related to the amount of requests . For example it could be time based , just to name a simple criteria , but there are multiple other potential factors that could affect the units returned that could be confused when using that name . could arguably make for a better name . 
 Not sure this should be closed by the PR , so feel free to reopen if that 's not the case . 
 thanks for your feedback ! You 're welcome to provide more ! to me it 's fine ! Good merge and good idea about the new name is cool :) 
 Thanks both ! I think this is more clear . 
 : +1 : Thanks ! I think this is more clear .
Paragraph (version A):
This document defines the RateLimit-Limit, RateLimit-Remaining,
RateLimit-Reset fields for HTTP, thus allowing servers to publish
current request quotas and clients to shape their request policy and
avoid being throttled out.
Paragraph (version B):
This document defines the RateLimit-Limit, RateLimit-Remaining,
RateLimit-Reset fields for HTTP, thus allowing servers to publish
current service limits and clients to shape their request policy and
avoid being throttled out.
Paragraph (version A):
The request-quota is a value associated to the maximum number of
requests that the server is willing to accept from one or more
clients on a given basis (originating IP, authenticated user,
geographical, ..) during a "time-window" as defined in time-window.
Paragraph (version A):
The "request-quota" SHOULD match the maximum number of acceptable
requests.
Paragraph (version A):
The "request-quota" MAY differ from the total number of acceptable
requests when weight mechanisms, bursts, or other server policies are
implemented.
Paragraph (version A):
If the "request-quota" does not match the maximum number of
acceptable requests the relation with that SHOULD be communicated
out-of-band.
Paragraph (version B):
The service-limit is a value associated to the maximum number of
requests that the server is willing to accept from one or more
clients on a given basis (originating IP, authenticated user,
geographical, ..) during a "time-window" as defined in time-window.
Paragraph (version B):
The "service-limit" SHOULD match the maximum number of acceptable
requests.
Paragraph (version B):
The "service-limit" MAY differ from the total number of acceptable
requests when weight mechanisms, bursts, or other server policies are
implemented.
Paragraph (version B):
If the "service-limit" does not match the maximum number of
acceptable requests the relation with that SHOULD be communicated
out-of-band.
Paragraph (version A):
The "RateLimit-Limit" response field indicates the "request-quota"
associated to the client in the current "time-window".
Paragraph (version A):
The "expiring-limit" value MUST be set to the "request-quota" that is
closer to reach its limit.
Paragraph (version B):
The "RateLimit-Limit" response field indicates the "service-limit"
associated to the client in the current "time-window".
Paragraph (version B):
The "expiring-limit" value MUST be set to the "service-limit" that is
closer to reach its limit.
Paragraph (version A):
The "RateLimit-Remaining" response field indicates the remaining
"quota-units" defined in request-quota associated to the client.
Paragraph (version B):
The "RateLimit-Remaining" response field indicates the remaining
"quota-units" defined in service-limit associated to the client.
Paragraph (version A):
The client MUST NOT assume that all its "request-quota" will be
restored after the moment referenced by "RateLimit-Reset".  The
server MAY arbitrarily alter the "RateLimit-Reset" value between
subsequent requests eg. in case of resource saturation or to
implement sliding window policies.
Paragraph (version B):
The client MUST NOT assume that all its "service-limit" will be
restored after the moment referenced by "RateLimit-Reset".  The
server MAY arbitrarily alter the "RateLimit-Reset" value between
subsequent requests eg. in case of resource saturation or to
implement sliding window policies.
Paragraph (version A):
does not guarantee that the next request will be successful.  Server
metrics may be subject to other conditions like the one shown in the
example from request-quota.
Paragraph (version B):
does not guarantee that the next request will be successful.  Server
metrics may be subject to other conditions like the one shown in the
example from service-limit.
Paragraph (version A):
A client MUST validate the values received in the "RateLimit" fields
before using them and check if there are significant discrepancies
with the expected ones.  This includes a "RateLimit-Reset" moment too
far in the future or a "request-quota" too high.
Paragraph (version B):
A client MUST validate the values received in the "RateLimit" fields
before using them and check if there are significant discrepancies
with the expected ones.  This includes a "RateLimit-Reset" moment too
far in the future or a "service-limit" too high.
Paragraph (version A):
The client exhausted its request-quota for the next 50 seconds.  The
"time-window" is communicated out-of-band or inferred by the field
values.
Paragraph (version B):
The client exhausted its service-limit for the next 50 seconds.  The
"time-window" is communicated out-of-band or inferred by the field
values.
Paragraph (version A):
Consider that "request-quota" may not be restored after the moment
referenced by "RateLimit-Reset", and the "RateLimit-Reset" value
should not be considered fixed nor constant.
Paragraph (version B):
Consider that "service-limit" may not be restored after the moment
referenced by "RateLimit-Reset", and the "RateLimit-Reset" value
should not be considered fixed nor constant.