jiebi/TextFlow huggingface dataset:
Original text:
4. A server uses the RateLimit header fields to communicate its quota <del> policies.  Sending the RateLimit-Limit and RateLimit-Reset header fields is REQUIRED; sending RateLimit-Remaining header field is RECOMMENDED. </del>  A server MAY return RateLimit header fields independently of the response status code.  This includes on throttled responses.  This

Reviewer comments:
NAME suggestion on server behavior. Thx! -
In section 4 it says, In section 4.1 it says, These statements seem contradictory. I do not see how we can declare as REQUIRED considering many APIs do not and will not implement these headers. It seems to me that if a client receives a header they can choose to either count the requests they make within the time window or they can monitor the . With neither of those values it would be difficult to do something useful. How would you feel about words like this:
NAME we are open to clarifications. The rationale for the current behavior is in URL I think RateLimit-Reset is always REQUIRED.
NAME In theory someone could use RateLimit-Limit to provide a limited number of "free" requests as a trial for their API. They may not choose to have a reset window and just require payment before allocating more calls. This is a bit of an edge case use of the headers, but might be just enough of a justification to limit constraints that we add. Having said this, I still don't understand how we can make any of these headers required considering there are so many existing APIs that don't return these headers today. How does a developer decide if they MUST return these headers for their API? Assuming the "free trial" scenario is not considered a valid scenario for this header, then how would you feel about these words?
SGTM.

Revised text:
4. A server uses the RateLimit header fields to communicate its quota  <ins> policies.  A response that includes the RateLimit-Limit header field MUST also include the RateLimit-Reset.  It MAY also include a RateLimit-Remaining header field. </ins> A server MAY return RateLimit header fields independently of the response status code.  This includes on throttled responses.  This
Original text:
informative. The field is a non-empty List of Items.  Each item is a quota-policy.  This field can convey the time window associated with the expiring- limit, as shown in this example: These examples show multiple policies being returned:  This field cannot appear in a trailer section. 3.3.

Reviewer comments:
clarify that quota policies are unique in policy.
If server defines two policies, e.g. and the response header contains, How do I know if I can make 2 more requests, or download 2 more bytes? Is having multiple policies with different quota units not allowed?
Good catch! The list items MUST be unique. I will specify this for now. WDYT about switching Policy to a Dictionary? This requires some tweak though e.g. prefixing the units with . cc: NAME
I'd use a short name for the policy, so that it could be referred to separately; e.g.,

Revised text:
informative. The field is a non-empty List of Items.  Each item is a quota-policy. <ins> Two quota policies MUST NOT be associated with the same quota units value. </ins> This field can convey the time window associated with the expiring- limit, as shown in this example: These examples show multiple policies being returned: <ins> An example of invalid header field value with two policies associated with the same quota units: </ins> This field cannot appear in a trailer section. 3.3.
Original text:
section. Clients MUST NOT assume that a positive "RateLimit-Remaining" value <del> is a guarantee of being served. </del>  <del> A low "RateLimit-Remaining" value is like a yellow traffic-light: the red light may arrive suddenly. </del>  One example of "RateLimit-Remaining" use is below. fields, "Retry-After" MUST take precedence and "RateLimit-Reset" MAY be ignored.  8. 8.1.

Reviewer comments:
specific throttling behavior is out of scope FAQ 8 integrated in RateLimit-Remaining and Receiving Ratelimit fields
We used the Limit and Remain values in one of our client applications that was migrated from a legacy SOAP service to our REST based API in order to ensure we never get a 429 response (this is because the legacy code could not gracefully retry requests without major refactoring). When we get to 80% of quota (20% Remain) we start respecting the value in the Reset header. In section 7 you touched on a concept ‘A client SHOULD NOT exceed the "quota-units" expressed in "RateLimit-Remaining" before the "time-window" expressed in "RateLimit-Reset".’ We don't want to mandate a strict behavior on client, but we can surely add this sentence as an example behavior. The current spec allows comments, so you can already do it. The spec allows to address this use-case transparently, by artificially lowering the values provided in the fields.
We should probably integrate and remove since it's already in the spec.
This is something I quickly commented on URL but the alternative of dynamically modifying the values as the rate saturates is fairly reasonable, so those informational parameters might as well be part of an extension document.

Revised text:
section. Clients MUST NOT assume that a positive "RateLimit-Remaining" value  <ins> is a guarantee that further requests will be served. </ins>  <ins> A low "RateLimit-Remaining" value is like a yellow traffic-light for either the number of requests issued in the "time-window" or the request throughput: the red light may arrive suddenly (see providing- ratelimit-fields). </ins> One example of "RateLimit-Remaining" use is below. fields, "Retry-After" MUST take precedence and "RateLimit-Reset" MAY be ignored. <ins> This specification does not mandate a specific throttling behavior and implementers can adopt their preferred policies, including: slowing down or preemptively backoff their request rate when approaching quota limits; consuming all the quota according to the exposed limits and then wait. </ins> 8. 8.1.
Original text:
Discussion of this draft takes place on the HTTP working group mailing list (httpapi@ietf.org), which is archived at <del> https://lists.w3.org/Archives/Public/ietf-httpapi-wg/ [1]. </del>  The source code and issues list for this draft can be found at https://github.com/ietf-wg-httpapi/ratelimit-headers [2]. 11.1.  URIs <del> [1] https://lists.w3.org/Archives/Public/ietf-httpapi-wg/ </del>  [2] https://github.com/ietf-wg-httpapi/ratelimit-headers

Reviewer comments:
Hi The link to the mailing archive (URL) is 404. I assume the correct link is: URL
Hi NAME thanks for the report, should be fixed soon.

Revised text:
Discussion of this draft takes place on the HTTP working group mailing list (httpapi@ietf.org), which is archived at  <ins> https://mailarchive.ietf.org/arch/browse/httpapi/ [1]. </ins> The source code and issues list for this draft can be found at https://github.com/ietf-wg-httpapi/ratelimit-headers [2]. 11.1.  URIs  <ins> [1] https://mailarchive.ietf.org/arch/browse/httpapi/ </ins> [2] https://github.com/ietf-wg-httpapi/ratelimit-headers
Original text:
10 requests per second; <del> limited to 60 request per minute; </del>  <del> limited to 1000 request per hour. </del>  Moreover system metrics, statistics and heuristics can be used to implement more complex policies, where the number of acceptable <del> request and the time window are computed dynamically. </del>  1.2. The goals of this proposal are: <del> Standardizing the names and semantics of rate-limit headers to ease their enforcement and adoption; </del>  Improve resiliency of HTTP infrastructure by providing clients with information useful to throttle their requests and prevent 4xx

Reviewer comments:
reformats goals
to reorganize Goals section with a single type of list
Single type of list as in using the same list styling for goals and non-goals? Or leaving just the list of goals and use prose for non-goals?

Revised text:
10 requests per second;  <ins> limited to 60 requests per minute; </ins>  <ins> limited to 1000 requests per hour. </ins> Moreover system metrics, statistics and heuristics can be used to implement more complex policies, where the number of acceptable  <ins> requests and the time window are computed dynamically. </ins> 1.2. The goals of this proposal are:  <ins> Standardization of the names and semantics of rate-limit headers to ease their enforcement and adoption; </ins> Improve resiliency of HTTP infrastructure by providing clients with information useful to throttle their requests and prevent 4xx
Original text:
<del> RateLimit Header Fields for HTTP </del>  draft-ietf-httpapi-ratelimit-headers-latest Abstract or 5xx responses; Simplify API documentation by eliminating the need to include <del> detailed quota limits and related header fields in API documentation. </del>  The goals do not include:

Reviewer comments:
consistent use of in document name cc: NAME NAME
Consistently use "fields" instead of "headers" since can be used in trailers.

Revised text:
 <ins> RateLimit Fields for HTTP </ins> draft-ietf-httpapi-ratelimit-headers-latest Abstract or 5xx responses; Simplify API documentation by eliminating the need to include  <ins> detailed quota limits and related fields in API documentation. </ins> The goals do not include:
Original text:
The "service-limit" is expressed in "quota-units" and has the following syntax: <del> where quota-units is a non-negative sf-integer. </del>  The "service-limit" SHOULD match the maximum number of acceptable requests. distribution of quota-units over time.  Such service specific details can be conveyed as parameters. <del> Two examples of providing further details via custom parameters </del>  3.

Reviewer comments:
clarify that quota-policy examples are not field values.
To clarify that examples in service-quota are not field-values

Revised text:
The "service-limit" is expressed in "quota-units" and has the following syntax:  <ins> where "quota-units" is a non-negative sf-integer. </ins> The "service-limit" SHOULD match the maximum number of acceptable requests. distribution of quota-units over time.  Such service specific details can be conveyed as parameters.  <ins> Two policy examples containing further details via custom parameters </ins> 3.
Original text:
The following parameters are defined: <del> The "w" parameter specifies a time window.  Its syntax is a "time- window" defined in time-window. </del>  Other parameters are allowed and can be regarded as comments.  They ought to be registered within the "Hypertext Transfer Protocol (HTTP)

Reviewer comments:
Clarifies that Without w a quota-policy is meaningless, so it's just a clarification.
Oops, this should have been explicit since day 1! Good catch!

Revised text:
The following parameters are defined:  <ins> The REQUIRED "w" parameter specifies a time window.  Its syntax is a "time-window" defined in time-window. </ins> Other parameters are allowed and can be regarded as comments.  They ought to be registered within the "Hypertext Transfer Protocol (HTTP)
Original text:
the CBOR and JSON representation of link format.  The RD resource paths /rd, /rd-lookup, and /rd-group are example values.  The server in this example also indicates that it is capable of providing <del> observation on lookup results. </del>  [ The RFC editor is asked to replace these and later occurrences of TBD64 and TBD504 with the numeric ID values assigned by IANA to

Reviewer comments:
Text changes after it seems that empty 2.05+Content-Format observed representations work. Example updated because it seems fitting for the RD to announce that capability. (Not that the indication changes anything about the possibility, but clients might not even try otherwise). Closes: URL NAME would this shortened text still satisfy your concerns?
For the example "obs" on rd-lookup/res is sufficient.
Hi Chris, thanks for all the work. We are making progress. I commented on 2 of the pull requests (typo and suggestion). Text is suggested for the commit on identification; I did not like the "debugging" annotation at all. Once everything is committed, I hope to go through it all again with today's knowledge. NAME I think Chris's text is terse but correct; can you close the issue, or suggest small changes? Thanks, peter chrysn schreef op 2018-01-31 19:25:
ad "obs in /rd-lookup/res only": I don't see why the server should, but it works just as well, so why argue, updated.
It is an example. It shows that not all needs to be observed. chrysn schreef op 2018-02-01 12:21:

Revised text:
the CBOR and JSON representation of link format.  The RD resource paths /rd, /rd-lookup, and /rd-group are example values.  The server in this example also indicates that it is capable of providing  <ins> observation on resource lookups. </ins> [ The RFC editor is asked to replace these and later occurrences of TBD64 and TBD504 with the numeric ID values assigned by IANA to
Original text:
NO  RD -> EP GET

Reviewer comments:
See the linked issues. Contributes-To: URL Closes: URL
Reduced (to the point where the PR's title is no longer really accurate), amended by oversights and split up into individual commits. NAME does this look better to you now? (The paragraph on the intention of the interaction templates is not in here yet, that'll be a separate PR.)
A con= value on a simple registration may be unintuitive to implementors (they'd expect to do role reversal when fetching the .well-known/core). We could disallow it, and would just need to state its implications (namely that endpoints that do virtual hosting or that register via CoAP-over-TCP can not use simple registration). The current patch for (b26dd6678e66e68ddb3850949f398bcf3c550416) already has this effect (but not yet the caveats wording). (Brought up during plug test, see )
8 Is there supposed to be a way for simple registration to return an error message? As written this is not necessarily done. Specifically, the response to the post can be executed before the query to /.well-known/core is done and the registration is attempted. I see what you mean: also the return of 2.04 shows in the example but not in the specification. This warrants additional text to specify the simple registration text. will add the simple registration template to the text.
Added template in section 5.3.1. simple registration
Ad "GET /.well-known/core": Our templates are already verbose, redundant with CoAP ("4.00 Bad Request and 400 Bad Request: Malformed request.", surprise) and at the same time not exhaustive (see ); I've come to accept that. But the GET section on the endpoint's .well-known/core is the very functionality that is described in RFC6690 Section 4. What is gained by duplicating that specification and selectively picking some possible error codes? I suggest we remove that part. Ad simple registration interface: Any particular reason you picked precisely ep and d to be eligible? lt definitely makes sense, and so do extra-attrs (they are our extension point, and not having them would exclude simple registration from extensibility). A pull request to that respect is pending (see link below) together with .
I think that's in a good state now with , , and the separator paragraph before the GET operation in #simple. I might have missed the point of this issue though, so not closing right away; NAME please close if you think this issue is done. Hi Christian, thanks for this very useful work Some questions/ remarks below. certainly not; it beats the purpose. We may add text in RD to address the TCP part. to what purpose? It states explicitly that it is a scheme//authority string, no query parameters possible; The simplicity helps to specify an already complex subject to be filled into the github, I hope. >

Revised text:
NO <ins> For the second interaction triggered by the above, the endpoint takes the role of a server: </ins> RD -> EP GET
Original text:
Lifetime (optional).  Lifetime of the registration in seconds. Range of 60-4294967295.  If no lifetime is included in the <del> initial registration, a default value of 86400 (24 hours) </del>  SHOULD be assumed. Context (optional).  This parameter sets the Default Base URI Lifetime (optional).  Lifetime of the registration in seconds. Range of 60-4294967295.  If no lifetime is included, the previous last lifetime set on a previous update or the original <del> registration (falling back to 86400) SHOULD be used. </del>  Context (optional).  This parameter updates the context established in the original registration to a new value.  If

Reviewer comments:
This is easier to to satisfy with a "once per day" update, a nice round number, and still over 9000. Closes: URL
I think that the default value of lt should be modified so that it is slightly greater than one day. If it is one day then a cron job which starts at midnight everyday could potentially end up not acting in time to renew rather than re-register an item. Given that a post to the resource adds the value of lt to the current time, there would be no drift in the expiration time.

Revised text:
Lifetime (optional).  Lifetime of the registration in seconds. Range of 60-4294967295.  If no lifetime is included in the  <ins> initial registration, a default value of 90000 (25 hours) </ins> SHOULD be assumed. Context (optional).  This parameter sets the Default Base URI Lifetime (optional).  Lifetime of the registration in seconds. Range of 60-4294967295.  If no lifetime is included, the previous last lifetime set on a previous update or the original  <ins> registration (falling back to 90000) SHOULD be used. </ins> Context (optional).  This parameter updates the context established in the original registration to a new value.  If
Original text:
authority information about an Endpoint.  The Context of an Endpoint is provided at registration time, and is used by the Resource Directory to resolve relative references inside the <del> registration into absolute URIs. </del>  The target of a link is the destination address (URI) of the link. It is sometimes identified with "href=", or displayed as "<target>".  Relative targets need resolving with respect to the <del> Base URI (section 5.2 of RFC3986. </del>  A resource in the Resource Directory (RD) containing registration

Reviewer comments:
With the formal introduction of Target in 68bd92a9, this seems even more important to point out. Next steps: merge unless someone protests.

Revised text:
authority information about an Endpoint.  The Context of an Endpoint is provided at registration time, and is used by the Resource Directory to resolve relative references inside the  <ins> registration into absolute URIs.  This is a distinct concept from the "link context" defined in RFC8288. </ins> The target of a link is the destination address (URI) of the link. It is sometimes identified with "href=", or displayed as "<target>".  Relative targets need resolving with respect to the  <ins> Base URI (section 5.2 of RFC3986.  This use of the term Target is consistent with RFC8288's use of the term. </ins> A resource in the Resource Directory (RD) containing registration
Original text:
endpoints and a resource lookup MUST return a list of links to resources. <del> The value of the lt attribute of the registration represents the time interval form the lookup moment till the end of life of the registration. </del> The lookup type is selected by a URI endpoint, which is indicated by a Resource Type as per lookup-types below: Endpoint and group lookups result in links to registration resources and group resources, respectively.  Endpoint registration resources <del> are annotated with their endpoint names (ep), domains (d, if present), context (con) and lifetime (lt, if present).  Additional </del>  endpoint attributes are added as link attributes to their endpoint link unless their specification says otherwise.  Group resources are annotated with their group names (gp), domain (d, if present) and

Reviewer comments:
We've had conflicting concepts (show remaining vs show registered), and they problematic w/rt caching and useless to some kinds of consumers, respectively. Given that there is no clear case for existing consumers that could fully work from those attributes in lookup, they're removed; when a use case does come up, it can still register a lookup parameter. Closes: URL
should lt value in lookup give time from specification moment to end or from lookup moment to end
added text in this sense in section 7
That's hard to keep consistent with caching. What use cases do we have for exposing a lifetime in the endpoint lookup at all?
returning the lt value as specified at registration time does not really help and can be omitted at lookup. Returning the remaining registration time till end of registration "could" be useful to a commissioning device that is unaware of the earlier registration time because it was not involved.
Given that caching of down-counting values is problematic, and the 'Returning the remaining [...] time [...] "could" be useful' does not sound too convinced, I'd suggest just not returning it by default and leaving it up to extensions to say what exactly they need. NAME is that something you'd be happy with?

Revised text:
endpoints and a resource lookup MUST return a list of links to resources.  The lookup type is selected by a URI endpoint, which is indicated by a Resource Type as per lookup-types below: Endpoint and group lookups result in links to registration resources and group resources, respectively.  Endpoint registration resources  <ins> are annotated with their endpoint names (ep), domains (d, if present) and context (con); the lifetime (lt) is not reported.  Additional </ins> endpoint attributes are added as link attributes to their endpoint link unless their specification says otherwise.  Group resources are annotated with their group names (gp), domain (d, if present) and
Original text:
filtering on groups would return a list of endpoints that are in the specified groups.  The lookup interface is specified as follows: Client -> RD

Reviewer comments:
Observe, ETag and possible future mechanisms are stated to be generally usable, but phrased as a "like with any other resource", because there is no need to actually define something new here.
Merged as agreed in the last call. NAME I'll address your comments in a different issue as I think they don't relate directly to that PR.
It would be good to provide a way for clients to receive notifications upon updates of an RD.
Is this something we need to specify? IMO it'd be orthogonal to the interface description -- if the RD advertises a , any client can try to observe the presence of endpoints.
So we should just say that such a lookup can be tried with observe, and that the link attribute "obs" is a good way to provide a hint. Any future optimized collection observe would probably use RD as a prominent example, so we can expect RD implementers to pick this up later.

Revised text:
filtering on groups would return a list of endpoints that are in the specified groups. <ins> Clients that are interested in a lookup result repeatedly or continuously can use mechanisms like ETag caching, resource observation (RFC7641), or any future mechanism that might allow more efficient observations of collections.  These are advertised, detected and used according to their own specifications and can be used with the lookup interface as with any other resource. </ins> The lookup interface is specified as follows: Client -> RD