Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: Reorganizes the document . See 
 [ x ] release -02 [ x ] include SF [ x ] include  's feedback cc : 
 To my eye , it takes a long time when reading to this document to actually come to the part where it tells you how rate limiting works . Often , IETF specifications give a high - level overview of concrete operation first , then define the specific protocol elements necessary , and only minimally address history , motivation , etc . That suggests an organisation like this : [ x ] 1 . Introduction ( considerably reducing the amount of background info , or moving it to an appendix ) [ x ] 2 . Expressing RateLimit Policies [ x ] 3 . Providing RateLimit Fields [ x ] 4 . Receiving RateLimit Fields Intermediaries Caching [ x ] 5 . Field Definitions [ x ] 6 . Examples ( or in an appendix ) 
 Thanks ! ! ! We 'll refactor :)
Paragraph (version A):
Still, there is not a standard way to communicate service quotas so
that the client can throttle its requests and prevent 4xx or 5xx
responses.
Paragraph (version A):
Servers use quota mechanisms to avoid systems overload, to ensure an
equitable distribution of computational resources or to enforce other
policies - e.g. monetization.
Paragraph (version A):
A basic quota mechanism limits the number of acceptable requests in a
given time window, e.g. 10 requests per second.
Paragraph (version A):
When quota is exceeded, servers usually do not serve the request
replying instead with a "4xx" HTTP status code (e.g. 429 or 403) or
adopt more aggressive policies like dropping connections.
Paragraph (version A):
limited to 1000 requests per hour.
Paragraph (version A):
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.
Paragraph (version A):
To help clients throttling their requests, servers may expose the
counters used to evaluate quota policies via HTTP header fields.
Paragraph (version A):
Those response headers may be added by HTTP intermediaries such as
API gateways and reverse proxies.
Paragraph (version A):
On the web we can find many different rate-limit headers, usually
containing the number of allowed requests in a given time window, and
when the window is reset.
Paragraph (version A):
header field names proliferates.
Paragraph (version A):
User Agents interfacing with different servers may thus need to
process different headers, or the very same application interface
that sits behind different reverse proxies may reply with different
throttling headers.
Paragraph (version B):
Widely deployed quota mechanisms limit the number of acceptable
requests in a given time window, e.g. 10 requests per second;
currently, there is no standard way to communicate service quotas so
that the client can throttle its requests and prevent 4xx or 5xx
responses.  See rate-limiting for further information on the current
usage of rate limiting in HTTP.
Paragraph (version A):
The rate-limit fields described here are not meant to support
authorization or other kinds of access controls.
Paragraph (version A):
The rate-limit fields may be returned in both successful (see
Section 15.3 of SEMANTICS) and non-successful responses.  This
specification does not cover whether non Successful responses
count on quota usage, nor it mandates any correlation between the
RateLimit values and the returned status code.
Paragraph (version B):
RateLimit fields are not meant to support authorization or other
kinds of access controls.
Paragraph (version B):
RateLimit fields may be returned in both successful (see
Section 15.3 of SEMANTICS) and non-successful responses.  This
specification does not cover whether non Successful responses
count on quota usage, nor it mandates any correlation between the
RateLimit values and the returned status code.
Paragraph (version A):
Servers should be careful in returning "RateLimit" fields in
redirection responses (e.g. 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.
Paragraph (version B):
Servers should be careful in returning "RateLimit" fields in
redirection responses (e.g. 3xx status codes) because a low
"RateLimit-Remaining" value could prevent 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.
Paragraph (version A):
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):
Since the field values are not necessarily correlated with the
response status code, a subsequent request is not required to fail.
The example below shows that the server decided to serve the request
even if "RateLimit-Remaining" is 0.  Another server, or the same
server under other load conditions, could have decided to throttle
the request instead.
Paragraph (version A):
the window will reset in 10 hours.
Paragraph (version A):
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):
The server adopted a basic policy of 100 quota-units per minute, and
in case of resource exhaustion adapts the returned values reducing
both "RateLimit-Limit" and "RateLimit-Remaining".
Paragraph (version A):
At the subsequent request - due to resource exhaustion - the server
advertises only "RateLimit-Remaining: 20".
Paragraph (version A):
A client exhausted its quota and the server throttles it sending
"Retry-After".
Paragraph (version A):
In this example, the values of "Retry-After" and "RateLimit-Reset"
reference the same moment, but this is not a requirement.
Paragraph (version A):
The "429 Too Many Requests" HTTP status code is just used as an
example.
Paragraph (version A):
The client has 99 "quota-units" left for the next 50 seconds.  The
"time-window" is communicated by the "w" parameter, so we know the
throughput is 100 "quota-units" per minute.
Paragraph (version A):
The policy conveyed by "RateLimit-Limit" states that the server
accepts 100 quota-units per minute.
Paragraph (version A):
To avoid resource exhaustion, the server artificially lowers the
actual limits returned in the throttling headers.
Paragraph (version A):
The "RateLimit-Remaining" then advertises only 9 quota-units for the
next 50 seconds to slow down the client.
Paragraph (version A):
Note that the server could have lowered even the other values in
"RateLimit-Limit": this specification does not mandate any relation
between the field values contained in subsequent responses.
Paragraph (version A):
Continuing the previous example, let's say the client waits 10
seconds and performs a new request which, due to resource exhaustion,
the server rejects and pushes back, advertising "RateLimit-Remaining:
0" for the next 20 seconds.
Paragraph (version A):
The server advertises a smaller window with a lower limit to slow
down the client for the rest of its original window after the 20
seconds elapse.
Paragraph (version A):
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,
e.g. 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
"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):
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.
Paragraph (version A):
It communicates to the client the limit of 10 quota-units per second
always returning the couple "RateLimit-Limit" and "RateLimit-Reset".
Paragraph (version A):
the "expiring-limit" is 5000.
Paragraph (version A):
Servers should not disclose operational capacity information that can
be used to saturate its resources.
Paragraph (version B):
Servers should not disclose to untrusted parties operational capacity
information that can be used to saturate its infrastructural
resources.
Paragraph (version A):
In case of resource saturation, the server MAY artificially lower the
returned values or not serve the request anyway.
Paragraph (version A):
Subsequent requests may return an higher "RateLimit-Reset" value to
limit concurrency or implement dynamic or adaptive throttling
policies.
Paragraph (version B):
In case of resource saturation, the server MAY artificially lower the
returned values or not serve the request regardless of the advertised
quotas.
Paragraph (version B):
Subsequent requests may return a higher "RateLimit-Reset" value to
limit concurrency or implement dynamic or adaptive throttling
policies.
Paragraph (version A):
Resource exhaustion issues can be associated with quota policies
using a large "time-window", because a user agent by chance or
purpose might consume most of its quota-units in a significantly
shorter interval.
Paragraph (version B):
Resource exhaustion issues can be associated with quota policies
using a large "time-window", because a user agent by chance or on
purpose might consume most of its quota-units in a significantly
shorter interval.