Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: uses field instead of header fix normative references 
 [ x ] always use fields , not headers [ ] reference latest SEMANTICS I - D [ x ] fix informative references
Paragraph (version A):
This was partially addressed with the "Retry-After" header field
defined in SEMANTICS to be returned in "429 Too Many Requests" or
"503 Service Unavailable" responses.
Paragraph (version B):
This was partially addressed by the "Retry-After" header field
defined in SEMANTICS to be returned in "429 Too Many Requests" (see
STATUS429) or "503 Service Unavailable" responses.
Paragraph (version A):
The rate-limit headers described here are not meant to support
authorization or other kinds of access controls.
Paragraph (version A):
The rate-limit headers may be returned in both Successful and non
Successful responses.  This specification does not cover whether
non Successful responses count on quota usage.
Paragraph (version A):
This specification does not mandate a specific throttling policy.
The values published in the headers, including the window size,
can be statically or dynamically evaluated.
Paragraph (version B):
The rate-limit fields described here are not meant to support
authorization or other kinds of access controls.
Paragraph (version B):
The rate-limit fields may be returned in both Successful and non
Successful responses.  This specification does not cover whether
non Successful responses count on quota usage.
Paragraph (version B):
This specification does not mandate a specific throttling policy.
The values published in the fields, including the window size, can
be statically or dynamically evaluated.
Paragraph (version A):
When using a policy involving more than one "time-window", the server
MUST reply with the "RateLimit" headers related to the window with
the lower "RateLimit-Remaining" values.
Paragraph (version B):
When using a policy involving more than one "time-window", the server
MUST reply with the "RateLimit" fields related to the window with the
lower "RateLimit-Remaining" values.
Paragraph (version A):
A client MUST process the received "RateLimit" headers.
Paragraph (version A):
A client MUST validate the values received in the "RateLimit" headers
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 A):
Malformed "RateLimit" headers MAY be ignored.
Paragraph (version B):
A client MUST process the received "RateLimit" fields.
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 "request-quota" too high.
Paragraph (version B):
Malformed "RateLimit" fields MAY be ignored.
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 informations (eg. the "Date" response header, 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 field, or
otherwise gathered metrics) to better estimate the "RateLimit-Reset"
moment intended by the server.
Paragraph (version A):
If a response contains both the "RateLimit-Reset" and "Retry-After"
fields, the "Retry-After" header field MUST take precedence and the
"RateLimit-Reset" field MAY be ignored.
Paragraph (version B):
If a response contains both the "RateLimit-Reset" and "Retry-After"
fields, "Retry-After" MUST take precedence and "RateLimit-Reset" MAY
be ignored.
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 header
values.
Paragraph (version B):
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 A):
Throttling headers may be used to limit concurrency, advertising
limits that are lower than the usual ones in case of saturation, thus
increasing availability.
Paragraph (version B):
Throttling fields may be used to limit concurrency, advertising
limits that are lower than the usual ones in case of saturation, thus
increasing availability.
Paragraph (version A):
A client exhausted its quota and the server throttles the request
sending the "Retry-After" response header field.
Paragraph (version B):
A client exhausted its quota and the server throttles it sending
"Retry-After".
Paragraph (version A):
Alternatively, given the same context where the previous example
starts, we can convey the same information to the client via the
Retry-After header, with the advantage that the server can now
specify the policy's nominal limit and window that will apply after
the reset, ie. assuming the resource exhaustion is likely to be gone
by then, so the advertised policy does not need to be adjusted, yet
we managed to stop requests for a while and slow down the rest of the
current window.
Paragraph (version A):
Note that in this last response the client is expected to honor the
"Retry-After" header and perform no requests for the specified amount
of time, whereas the previous example would not force the client to
stop requests before the reset time is elapsed, as it would still be
free to query again the server even if it is likely to have the
request rejected.
Paragraph (version B):
Alternatively, given the same context where the previous example
starts, we can convey the same information to the client via "Retry-
After", with the advantage that the server can now specify the
policy's nominal limit and window that will apply after the reset,
ie. assuming the resource exhaustion is likely to be gone by then, so
the advertised policy does not need to be adjusted, yet we managed to
stop requests for a while and slow down the rest of the current
window.
Paragraph (version B):
Note that in this last response the client is expected to honor
"Retry-After" and perform no requests for the specified amount of
time, whereas the previous example would not force the client to stop
requests before the reset time is elapsed, as it would still be free
to query again the server even if it is likely to have the request
rejected.
Paragraph (version A):
Servers should not disclose operational capacity informations that
can be used to saturate its resources.
Paragraph (version A):
While this specification does not mandate whether non 2xx responses
consume quota, if 401 and 403 responses count on quota a malicious
client could probe the endpoint to get traffic informations of
another user.
Paragraph (version A):
As intermediaries might retransmit requests and consume quota-units
without prior knowledge of the User Agent, RateLimit headers might
reveal the existence of an intermediary to the User Agent.
Paragraph (version A):
"RateLimit-*" headers convey hints from the server to the clients in
order to avoid being throttled out.
Paragraph (version B):
Servers should not disclose operational capacity information that can
be used to saturate its resources.
Paragraph (version B):
While this specification does not mandate whether non 2xx responses
consume quota, if 401 and 403 responses count on quota a malicious
client could probe the endpoint to get traffic information of another
user.
Paragraph (version B):
As intermediaries might retransmit requests and consume quota-units
without prior knowledge of the User Agent, RateLimit fields might
reveal the existence of an intermediary to the User Agent.
Paragraph (version B):
"RateLimit-*" fields convey hints from the server to the clients in
order to avoid being throttled out.