Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: Section 2.2 : Section 2.3 : This appears to be a circular definition -- what 's actually being defined here ? 
 ( noting that 2.2 does n't actually define quota - units ) 
 Quota unit is now defined as the measurement unit for service limits . 
 PTAL - I tried to rearrange to address this a bit more holistically . 
 Looks good!LGTM
Paragraph (version A):
A quota policy is described in terms of service-limit and a time-
window.  It is an Item whose bare item is a service-limit, along with
associated Parameters.
Paragraph (version A):
The REQUIRED "w" parameter value conveys a time window value as
defined in time-window.
Paragraph (version A):
Other parameters are allowed and can be regarded as comments.  They
ought to be registered within the "Hypertext Transfer Protocol (HTTP)
RateLimit Parameters Registry", as described in iana-ratelimit-
parameters.
Paragraph (version A):
The definition of a quota policy does not imply any specific
distribution of quota units within the time window.  If applicable,
these details can be conveyed as extension parameters.
Paragraph (version A):
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.
Paragraph (version A):
Rate limit policies limit the number of acceptable requests within a
given time interval, known as a time window.
Paragraph (version A):
The service limit is associated with 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.
Paragraph (version A):
The service limit is a non-negative Integer expressed in quota units.
Paragraph (version A):
The service limit SHOULD match the maximum number of acceptable
requests.  However, the service limit MAY differ from the total
number of acceptable requests when weight mechanisms, bursts, or
other server policies are implemented.
Paragraph (version A):
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 B):
A quota policy is maintained by a server to limit the activity
(counted in quota units) of a given client over a period of time
(known as the time-window) to a specified amount (known as the
service-limit).
Paragraph (version B):
Quota policies can be advertised by servers (see ratelimit-policy-
field), but they are not required to be, and more than one quota
policy can affect a given request from a client to a server.
Paragraph (version B):
A quota policy is expressed in Structured Fields STRUCTURED-FIELDS as
an Integer that indicates the service limit with associated
parameters.
Paragraph (version B):
The REQUIRED "w" parameter value conveys a time window (time-
window).
Paragraph (version B):
Other parameters are allowed and can be regarded as comments.
Parameters for use by more than one implementation or service ought
to be registered within the "Hypertext Transfer Protocol (HTTP)
RateLimit Parameters Registry", as described in iana-ratelimit-
parameters.
Paragraph (version B):
Implementation- or service-specific parameters SHOULD be prefixed
parameters with a vendor identifier, e.g. "acme-policy", "acme-
burst".
Paragraph (version B):
The service limit is a non-negative Integer indicating the maximum
amount of activity that the server is willing to accept from what it
identifies as the client (e.g., based upon originating IP or user
authentication) during a time-window.
Paragraph (version B):
The activity being limited is usually the HTTP requests made by the
client; for example "you can make 100 requests per minute".  However,
a server might only rate limit some requests (based upon URI, method,
user identity, etc.), and it might weigh requests differently.
Therefore, quota policies are defined in terms of "quota units".
Servers SHOULD document how they count quota units.
Paragraph (version B):
Often, the service limit advertised will match the server's actual
limit.  However, it MAY differ when weight mechanisms, bursts, or
other server policies are implemented.  In that case the difference
SHOULD be communicated using an extension or documented separately.
Paragraph (version B):
Quota policies limit the number of acceptable requests within a given
time interval, known as a time window.
Paragraph (version B):
By default, a quota policy does not constrain the distribution of
quota units within the time window.  If necessary, these details can
be conveyed as extension parameters.