Merge pull request #146 from ietf-wg-httpapi/IETF122

Feedback from IETF 121

Author: darrelmiller

draft-ietf-httpapi-ratelimit-headers.md

@@ -125,16 +125,26 @@ This document uses the terms List, Item and Integer from {{Section 3 of !STRUCTU
   Service Limit:
   : A service limit is the currently remaining quota from a specific quota policy and, if defined, the remaining time before quota is reallocated.
 
+  List:
+  : A {{!STRUCTURED-FIELDS=RFC8941}} list of Items
+
+  Item:
+  : A {{!STRUCTURED-FIELDS=RFC8941}} item with a set of associated parameters
+
 # RateLimit-Policy Field {#ratelimit-policy-field}
 
-The "RateLimit-Policy" response header field is a non-empty List of Quota Policy Items ({{quotapolicy-item}}). The Item value MUST be a String. Its value is informative. The field value is expected to remain consistent over the lifetime of a connection. It is this characteristic that differentiates it from the [RateLimit](#ratelimit-field) field that contains information that may change on every request.
+The "RateLimit-Policy" response header field is a non-empty List{{!RFC8941}} of Quota Policy Items ({{quotapolicy-item}}). The Item{{!RFC8941}} value MUST be a String{{!RFC8941}}.
+
+The field value SHOULD remain consistent over a sequence of HTTP responses. It is this characteristic that differentiates it from the [RateLimit](#ratelimit-field) field that contains information that MAY change on every request. The "RateLimit-Policy" field enables clients to control their own flow of requests based on policy information provided by the server. Situations where throttling constraints are highly dynamic are better served using the (RateLimit field)[{#ratelimit-field}] that communicates the latest service information a client can react to. Both fields can be communicated by the server when appropriate.
+
+Lists of Quota Policy Items ({{quotapolicy-item}}) can be split over multiple "RateLimit-Policy" fields in the same HTTP response as described in {{Section 3.1 of !STRUCTURED-FIELDS=RFC8941}}.
 
 ~~~
    RateLimit-Policy: "burst";q=100;w=60,"daily";q=1000;w=86400
 ~~~
 
 ## Quota Policy Item {#quotapolicy-item}
-A quota policy Item contains an identifier for the policy and a set of parameters that contain information about a server's capacity allocation for the policy.
+A quota policy Item contains an identifier for the policy and a set of Parameters{{!RFC8941}} that contain information about a server's capacity allocation for the policy.
 
 The following parameters are defined:
 
@@ -154,7 +164,7 @@ Other parameters are allowed and can be regarded as comments.
 
 Implementation- or service-specific parameters SHOULD be prefixed parameters with a vendor identifier, e.g. `acme-policy`, `acme-burst`.
 
-This field cannot appear in a trailer section.
+This field MUST NOT appear in a trailer section.
 
 ### Quota Parameter {#ratelimitpolicy-quota}
 
@@ -175,7 +185,7 @@ The "qu" parameter value conveys the quota units applicable to the quota ({{rate
 
 ### Window Parameter {#ratelimitpolicy-window}
 
-The "w" parameter value conveys a time window applicable to the quota ({{ratelimitpolicy-quota}}). The time window MUST be a non-negative Integer value expressing an interval in seconds, similar to the "delay-seconds" rule defined in {{Section 10.2.3 of HTTP}}. Sub-second precision is not supported.
+The "w" parameter value conveys a time window applicable to the quota ({{ratelimitpolicy-quota}}). The time window MUST be a non-negative, non-zero, Integer value expressing an interval in seconds, similar to the "delay-seconds" rule defined in {{Section 10.2.3 of HTTP}}. Sub-second precision is not supported.
 
 ### Partition Key Parameter {#ratelimitpolicy-partitionkey}
 
@@ -204,22 +214,24 @@ The following example shows a policy with a partition key:
 The following example shows a policy with a partition key and a quota unit:
 
 ~~~
-   RateLimit-Policy: "peruser";q=65535;qu="bytes";w=10;pk=:sdfjLJUOUH==:
+   RateLimit-Policy: "peruser";q=65535;qu="content-bytes";w=10;pk=:sdfjLJUOUH==:
 ~~~
 
 # RateLimit Field {#ratelimit-field}
 
-A server uses the "RateLimit" response header field to communicate the service limit for a quota policy for a particular partition key.
+A server uses the "RateLimit" response header field to communicate the current service limit for a quota policy for a particular partition key.
+
+The field is expressed as a List{{!RFC8941}} of Service Limit Items ({{servicelimit-item}}).
 
-The field is expressed as a List of Service Limit Items ({{servicelimit-item}}).
+Lists of Service Limit Items can be split over multiple "RateLimit" fields in the same HTTP response as described in {{Section 3.1 of !STRUCTURED-FIELDS=RFC8941}}.
 
 ~~~
    RateLimit: "default";r=50;t=30
 ~~~
 
 ## Service Limit Item {#servicelimit-item}
 
-Each service limit Item identifies the quota policy ({{quotapolicy-item}}) associated with the request and contains parameters with information about the current service limit.
+Each service limit Item{{!RFC8941}} identifies the quota policy ({{quotapolicy-item}}) associated with the request and contains Parameters{{!RFC8941}} with information about the current service limit.
 
 The following parameters are defined in this specification: