This document defines the RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset fields for HTTP, thus allowing servers to publish <del> current request quotas and clients to shape their request policy and </del>  avoid being throttled out. Note to Readers 2.2. <del> The request-quota is a value associated to the maximum number of </del>  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" as defined in time-window. <del> The "request-quota" is expressed in "quota-units" and has the </del>  following syntax: <del> The "request-quota" SHOULD match the maximum number of acceptable </del>  requests. <del> The "request-quota" MAY differ from the total number of acceptable </del>  requests when weight mechanisms, bursts, or other server policies are implemented. <del> If the "request-quota" does not match the maximum number of </del>  acceptable requests the relation with that SHOULD be communicated out-of-band. 3.1. <del> The "RateLimit-Limit" response field indicates the "request-quota" </del>  associated to the client in the current "time-window". If the client exceeds that limit, it MAY not be served. The field value is <del> The "expiring-limit" value MUST be set to the "request-quota" that is </del>  closer to reach its limit. The "quota-policy" is defined in quota-policy, and its values are 3.2. The "RateLimit-Remaining" response field indicates the remaining <del> "quota-units" defined in request-quota associated to the client. </del>  The field value is An example of "RateLimit-Reset" use is below. <del> The client MUST NOT assume that all its "request-quota" will be </del>  restored after the moment referenced by "RateLimit-Reset".  The server MAY arbitrarily alter the "RateLimit-Reset" value between subsequent requests eg. in case of resource saturation or to does not guarantee that the next request will be successful.  Server metrics may be subject to other conditions like the one shown in the <del> example from request-quota. </del>  A server MAY return "RateLimit" response fields independently of the response status code.  This includes throttled responses. 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 <del> far in the future or a "request-quota" too high. </del>  Malformed "RateLimit" fields MAY be ignored. 8.1.1. <del> The client exhausted its request-quota for the next 50 seconds.  The </del>  "time-window" is communicated out-of-band or inferred by the field values. 9.4. <del> Consider that "request-quota" may not be restored after the moment </del>  referenced by "RateLimit-Reset", and the "RateLimit-Reset" value should not be considered fixed nor constant.

Improves terminology replacing with . cc: NAME NAME
It seems in the context of this design limit and quota terminology mean the same thing, however the header name to represent quota is RateLimit-Limit, which stutters. Would RateLimit-Quota not be better because it seems to mean the same thing and avoids stuttering?
Well, conveys the , which is expressed in terms of . The name makes me think more to a than to or . Since implementers already use , with NAME we decided not to change field names. WDYT to rename instead?
One potential issue with is that the quota can be not directly related to the amount of requests. For example it could be time based, just to name a simple criteria, but there are multiple other potential factors that could affect the units returned that could be confused when using that name. could arguably make for a better name.
Not sure this should be closed by the PR, so feel free to reopen if that's not the case.
NAME thanks for your feedback! You're welcome to provide more! NAME to me it's fine! Good merge and good idea about the new name is cool :)
Thanks both! I think this is more clear.
:+1:Thanks! I think this is more clear.

This document defines the RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset fields for HTTP, thus allowing servers to publish  <ins> current service limits and clients to shape their request policy and </ins> avoid being throttled out. Note to Readers 2.2.  <ins> The service-limit is a value associated to the maximum number of </ins> 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" as defined in time-window.  <ins> The "service-limit" is expressed in "quota-units" and has the </ins> following syntax:  <ins> The "service-limit" SHOULD match the maximum number of acceptable </ins> requests.  <ins> The "service-limit" MAY differ from the total number of acceptable </ins> requests when weight mechanisms, bursts, or other server policies are implemented.  <ins> If the "service-limit" does not match the maximum number of </ins> acceptable requests the relation with that SHOULD be communicated out-of-band. 3.1.  <ins> The "RateLimit-Limit" response field indicates the "service-limit" </ins> associated to the client in the current "time-window". If the client exceeds that limit, it MAY not be served. The field value is  <ins> The "expiring-limit" value MUST be set to the "service-limit" that is </ins> closer to reach its limit. The "quota-policy" is defined in quota-policy, and its values are 3.2. The "RateLimit-Remaining" response field indicates the remaining  <ins> "quota-units" defined in service-limit associated to the client. </ins> The field value is An example of "RateLimit-Reset" use is below.  <ins> The client MUST NOT assume that all its "service-limit" will be </ins> restored after the moment referenced by "RateLimit-Reset".  The server MAY arbitrarily alter the "RateLimit-Reset" value between subsequent requests eg. in case of resource saturation or to does not guarantee that the next request will be successful.  Server metrics may be subject to other conditions like the one shown in the  <ins> example from service-limit. </ins> A server MAY return "RateLimit" response fields independently of the response status code.  This includes throttled responses. 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  <ins> far in the future or a "service-limit" too high. </ins> Malformed "RateLimit" fields MAY be ignored. 8.1.1.  <ins> The client exhausted its service-limit for the next 50 seconds.  The </ins> "time-window" is communicated out-of-band or inferred by the field values. 9.4.  <ins> Consider that "service-limit" may not be restored after the moment </ins> referenced by "RateLimit-Reset", and the "RateLimit-Reset" value should not be considered fixed nor constant.


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.

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.

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.


A server MAY return "RateLimit" response fields independently of the response status code.  This includes throttled responses.  If a response contains both the "Retry-After" and the "RateLimit- Reset" fields, the value of "RateLimit-Reset" SHOULD reference the same point in time as "Retry-After".

clarifies interaxtions with 3xx
Note that here we clash with the scope of these fields. Do they refer to the current request which for whatever reason ends up in a redirection or do they refer to the request that will follow up to the target location? We have been careful to always talk about the current request and leave the scope undefined but one way or another contained in this request (ie. the same service, the same path prefix, the same domain, the same hour, or any other criteria that can emerge from the fact we are performing this particular request). With the fields applied to the follow up redirection this could change, because the target location could be any URL. So what would happen if we really wanted to limit the endpoint that causes the redirection instead of the target location? A point can be made about these values being of no use when an endpoint is redirected, but if the redirection was conditional or temporary, we'd lose the ability to convey these limits. In addition, a redirect might target a different service altogether, potentially with its own policies this service might know nothing about. I think giving a different meaning to these values in the case of redirection creates an exception that does not carry enough weight. In the general case where a redirection is permanent, you can simply assume as a client that you need to call at least once the target location in order to obtain rate limiting information. After all, your request was serviced, not refused, so if the target was under the control of this service and it determined that you have no quota, it could just as well refuse to respond with the redirect and instead send back a 429 or some other client error status rather than waiting for you to perform another request only to then refuse to service it.
I tried to be non-normative, and just warn implementers - both client and server - to be carefull when 3xx and I avoided providing details (eg. whether is on the same service or not). But I think you can provide a better wording: if you think this should be placed elsewhere (eg. Security considerations) feel free to do it! :rocket:
NAME PTAL :)
I think providing a reminder to the server implementer that if you are going to return a redirect and you know it is to the same API, then it would unwise to return a 0 in the RateLimit-Remaining. This feels like a valuable reminder to me.
No Correct Probably we should warn that returning a with 30x could refrain clients to make a request, but I won't be normative on that cc: NAME
See We need to provide guidance in redirection cases, probably.

A server MAY return "RateLimit" response fields independently of the response status code.  This includes throttled responses. <ins> Servers should be careful in returning "RateLimit" fields in redirection responses (eg. 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. </ins> If a response contains both the "Retry-After" and the "RateLimit- Reset" fields, the value of "RateLimit-Reset" SHOULD reference the same point in time as "Retry-After".


be the given resource-target, its parent path or the whole Origin (see Section 7 of RFC6454). <del> 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. </del>  This specification does not mandate a specific throttling policy. The values published in the fields, including the window size, can A server MAY return "RateLimit" response fields independently of the response status code.  This includes throttled responses.  Servers should be careful in returning "RateLimit" fields in redirection responses (eg. 3xx status codes) because a low "RateLimit-Remaining" value could limit the client from issuing Response:  8.1.2. The server uses two custom fields, namely "acme-RateLimit-DayLimit"

clarifies that status code is independent from the values of RL fields the example reflects the above statement.
Would there be scope to define standards for the 429 response or would that be more relevant to RFC6585. Should RFC6585 be extended to mention this RFC ?
This I-D is independent from the status code of the response, so I'd say there are no normative relations between this doc and RFC6585. This is by design: we just want to standardize response fields without explicitly define a "ratelimit protocol". Instead, we want implementers to be free to implement their throttling strategies.
See. URL
I noticed in the example in You return a 200 response with RateLimit-Remaining: 0 . It is not completely clear in the document that a remaining value of 0 should be returned to the caller as a success when the quota has been used exactly. In you present a case where the cost of a more expensive call deducts two from the remaining pool and results in a 429. I am conflicted as to whether it should be a server decision whether the call is respected or whether the spec should strictly define this behaviour. I lean toward the former but some feel guidance is needed.
we should clarify that this is a server choice. The spec does not mandate any correlation between the RL values and the returned status code . The server can always decide to serve requests even when quota is over. We need to clarify this both in the text and in the example.
That is something that was not clear to me when reading the spec. The assumption being that when is exhausted, a user will be rate limited and an error response (429) will be issued. It would seem as per and that there is no specific intention to require a server implementation to deny further responses, but rather in some cases the expectation would be for the client to gracefully comply and back off. My feeling is though that this use case would be the exception rather than the rule, with most implementations opting to deny further requests. Should we not at least provide guidance that a 429 response should be issued in this scenario ?

be the given resource-target, its parent path or the whole Origin (see Section 7 of RFC6454).  <ins> 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. </ins> This specification does not mandate a specific throttling policy. The values published in the fields, including the window size, can A server MAY return "RateLimit" response fields independently of the response status code.  This includes throttled responses. <ins> This document does not mandate any correlation between the "RateLimit" values and the returned status code. </ins> Servers should be careful in returning "RateLimit" fields in redirection responses (eg. 3xx status codes) because a low "RateLimit-Remaining" value could limit the client from issuing Response: <ins> 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. Request: Response: </ins> 8.1.2. The server uses two custom fields, namely "acme-RateLimit-DayLimit"


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

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.

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


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

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?

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


The term Origin is to be interpreted as described in Section 7 of RFC6454. <del> The "delay-seconds" rule is defined in Section 10.2.3 of SEMANTICS. </del>  2. A time window is expressed in seconds, using the following syntax:  Subsecond precision is not supported. 2.2. The "service-limit" is expressed in "quota-units" and has the following syntax:  The "service-limit" SHOULD match the maximum number of acceptable requests. This specification allows describing a quota policy with the following syntax: <del> quota-policy parameters like "w" and quota-comment tokens MUST NOT occur multiple times within the same quota-policy. </del>  An example policy of 100 quota-units per minute. The definition of a quota-policy does not imply any specific distribution of quota-units over time.  Such service specific details <del> can be conveyed in the "quota-comments". </del>  <del> Two examples of providing further details via custom parameters in "quota-comments". </del>  3. If the client exceeds that limit, it MAY not be served. <del> The field value is </del>  The "expiring-limit" value MUST be set to the "service-limit" that is closer to reach its limit. The "RateLimit-Remaining" response field indicates the remaining "quota-units" defined in service-limit associated to the client. <del> The field value is </del>  This field MUST NOT occur multiple times and can be sent in a trailer section. the number of seconds until the quota resets. <del> The field value is </del>  The delay-seconds format is used because:

uses structured fields based on NAME preliminary work: thanks!!!referencing the RFC distinguishing sf-item and sf-integer, since sf-integer do not support parameters whereas sf-item does retaining the intermediate syntaxes (quota-policy, quota-units, service-limit, ...)
LGTM, waiting on ack from NAME before merging.
NAME thanks for reviewing! Can we merge?
It's your draft :)
I take it for a YES :D
Since parameters are always allowed in Limit we could define a "registry" and add them subsequently as soon as implementers needs them. They can be used to specify: max throughputs request distribution other policies All data in parameters is informative.
I assume there must be previous art in keeping a registry like this that we can mimic, but I can't think of a good example off the top of my head that wouldn't be using a separate registry or document to manage that. What's your thinking about where to keep this registry?
NAME registries are usually maintained by IANA: we can check with NAME if that's possible...
We can pretty easily define a registry. You include a section in the RFC. See URL You define a table that is the registry, and meanings of the columns, and perhaps populate it with the initial entries. The WG decides some rules, like "X-" is left for experimentation. There must be something written (it can be an internet draft or something else on the net), whether a set of "experts" need to review for comliance and clarity, and so on.
If you'd like, I can make a PR that provides the initial text for this next week.
Yes, that would be great NAME
Can you give me an initial set of fields (even if it's just one or two), and an example, and a pointer to which section in the current draft? thanks.
Hi NAME Thanks for your support! To make best use of your time, I'd wait for to be merged (waiting for mnot's review) so you can PR directly vs . WRT the parameter registry: currently the initial set is just : See: URL Do you have a proposal for the registration policy?
Thanks, I'll wait. I think it should be expert review. That means that there should be a document describing the parameter, and that the experts can be directed to verify that the documentation is clear and unambiguous, and that there is no significant overlap with the parameters already defined. The other choices are "specification required" and "first-come first-served."
NAME we just merged structured fields in RateLimit Headers!
Thanks for the ping, I saw :) I'll propose a PR soon.
URL I think it needs to be tweaked, since it's just defined as a "quota" registry in that PR. Should it be a ratelimit fields registry?

The term Origin is to be interpreted as described in Section 7 of RFC6454.  <ins> This specification uses Structured Fields SF to specify syntax. The terms sf-list, sf-item, sf-string, sf-token, sf-integer, bare- item and key refer to the structured types defined therein. </ins> 2. A time window is expressed in seconds, using the following syntax: <ins> Where "delay-seconds" is a non-negative sf-integer compatible with the "delay-seconds" rule defined in Section 10.2.3 of SEMANTICS. </ins> Subsecond precision is not supported. 2.2. 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. This specification allows describing a quota policy with the following syntax:  <ins> where the associated bare-item is a service-limit and parameters are supported. The following parameters are defined: The "w" parameter specifies a time window.  Its syntax is a "time- window" defined in time-window. Other parameters are allowed and can be regarded as comments. </ins> An example policy of 100 quota-units per minute. The definition of a quota-policy does not imply any specific distribution of quota-units over time.  Such service specific details  <ins> can be conveyed as parameters. </ins>  <ins> Two examples of providing further details via custom parameters </ins> 3. If the client exceeds that limit, it MAY not be served.  <ins> The field is a List Structured Field of positive length.  The first member is named "expiring-limit" and its syntax is "service-limit", while the syntax of the other optional members is "quota-policy" </ins> The "expiring-limit" value MUST be set to the "service-limit" that is closer to reach its limit. The "RateLimit-Remaining" response field indicates the remaining "quota-units" defined in service-limit associated to the client.  <ins> The field is an Integer Structured Field and its value is </ins> This field MUST NOT occur multiple times and can be sent in a trailer section. the number of seconds until the quota resets.  <ins> The field is an Integer Structured Field and its value is </ins> The delay-seconds format is used because:


The source code and issues list for this draft can be found at https://github.com/ietf-wg-httpapi/ratelimit-headers [2].  1. The widespreading of HTTP as a distributed computation protocol 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. </del>  An example policy of 100 quota-units per minute. 10. <del> 10.1. This section registers the "RateLimit-Limit" field in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" registry (SEMANTICS). Field name: "RateLimit-Limit" </del>  <del> Status: permanent </del>  <del> Specification document(s): ratelimit-limit-field of this document 10.2. This section registers the "RateLimit-Remaining" field in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" registry (SEMANTICS). </del>  <del> Field name: "RateLimit-Remaining" </del>  <del> Status: permanent </del>  <del> Specification document(s): ratelimit-remaining-field of this document </del>  <del> 10.3. </del>  <del> This section registers the "RateLimit-Reset" field in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" registry (SEMANTICS). </del>  <del> Field name: "RateLimit-Reset" </del>  <del> Status: permanent </del>  <del> Specification document(s): ratelimit-reset-field of this document </del>  11.  References [1] https://mailarchive.ietf.org/arch/browse/httpapi/ [2] https://github.com/ietf-wg-httpapi/ratelimit-headers

Merge three "add to table" into one request to "add these to the table" Create a new registry for quota fields.
looks good!
NAME NAME I made some edits: ad an addressable subsection for iana-ratelimit-parameters add , to iana table reference specification sections in IANA registries removed normative parts from IANA mention IANA table in {{quota-policy}} Could you please PTAL?
ooops I missed your comment :) Ok, let's merge.
Since parameters are always allowed in Limit we could define a "registry" and add them subsequently as soon as implementers needs them. They can be used to specify: max throughputs request distribution other policies All data in parameters is informative.
I assume there must be previous art in keeping a registry like this that we can mimic, but I can't think of a good example off the top of my head that wouldn't be using a separate registry or document to manage that. What's your thinking about where to keep this registry?
NAME registries are usually maintained by IANA: we can check with NAME if that's possible...
We can pretty easily define a registry. You include a section in the RFC. See URL You define a table that is the registry, and meanings of the columns, and perhaps populate it with the initial entries. The WG decides some rules, like "X-" is left for experimentation. There must be something written (it can be an internet draft or something else on the net), whether a set of "experts" need to review for comliance and clarity, and so on.
If you'd like, I can make a PR that provides the initial text for this next week.
Yes, that would be great NAME
Can you give me an initial set of fields (even if it's just one or two), and an example, and a pointer to which section in the current draft? thanks.
Hi NAME Thanks for your support! To make best use of your time, I'd wait for to be merged (waiting for mnot's review) so you can PR directly vs . WRT the parameter registry: currently the initial set is just : See: URL Do you have a proposal for the registration policy?
Thanks, I'll wait. I think it should be expert review. That means that there should be a document describing the parameter, and that the experts can be directed to verify that the documentation is clear and unambiguous, and that there is no significant overlap with the parameters already defined. The other choices are "specification required" and "first-come first-served."
NAME we just merged structured fields in RateLimit Headers!
Thanks for the ping, I saw :) I'll propose a PR soon.
URL I think it needs to be tweaked, since it's just defined as a "quota" registry in that PR. Should it be a ratelimit fields registry?

The source code and issues list for this draft can be found at https://github.com/ietf-wg-httpapi/ratelimit-headers [2]. <ins> References to "ThisRFC" in the IANA Considerations section would be replaced with the RFC number when assigned. </ins> 1. The widespreading of HTTP as a distributed computation protocol The "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) RateLimit Parameters Registry", as described in iana-ratelimit- parameters. </ins> An example policy of 100 quota-units per minute. 10.  <ins> IANA is requested to update one registry and create one new registry. </ins>  <ins> Please add the following entries to the "Hypertext Transfer Protocol (HTTP) Field Name Registry" registry (SEMANTICS): </ins>  <ins> 10.1. </ins>  <ins> IANA is requested to create a new registry to be called "Hypertext Transfer Protocol (HTTP) RateLimit Parameters Registry", to be located at https://www.iana.org/assignments/http-ratelimit-parameters [3].  Registration is done on the advice of a Designated Expert, appointed by the IESG or their delegate.  All entries are Specification Required (IANA, Section 4.6). </ins>  <ins> Registration requests consist of the following information: </ins>  <ins> Parameter name: The parameter name, conforming to SF. </ins>  <ins> Field name: The RateLimit field for which the parameter is registered.  If a parameter is intended to be used with multiple fields, it has to be registered for each one. </ins>  <ins> Description: A brief description of the parameter. </ins>  <ins> Specification document: A reference to the document that specifies the parameter, preferably including a URI that can be used to retrieve a copy of the document. </ins>  <ins> Comments (optional): Any additional information that can be useful. </ins>  <ins> The initial contents of this registry should be: </ins> 11.  References [1] https://mailarchive.ietf.org/arch/browse/httpapi/ [2] https://github.com/ietf-wg-httpapi/ratelimit-headers <ins> [3] https://www.iana.org/assignments/http-ratelimit-parameters </ins>


Servers use quota mechanisms to avoid systems overload, to ensure an equitable distribution of computational resources or to enforce other <del> policies - eg. monetization. </del>  A basic quota mechanism limits the number of acceptable requests in a <del> given time window, eg. 10 requests per second. </del>  When quota is exceeded, servers usually do not serve the request <del> replying instead with a "4xx" HTTP status code (eg. 429 or 403) or </del>  adopt more aggressive policies like dropping connections. <del> Quotas may be enforced on different basis (eg. per user, per IP, per </del>  geographic area, ..) and at different levels.  For example, an user may be allowed to issue: count once requests like "/books/{id}" <del> count twice search requests like "/books?author=Camilleri" </del>  so that we have the following counters inferred by the value of "RateLimit-Reset" at the moment of the reset, or <del> communicated out-of-band (eg. in the documentation). </del>  Policies using multiple quota limits MAY be returned using multiple "quota-policy" items, like shown in the following two examples: The client MUST NOT assume that all its "service-limit" will be restored after the moment referenced by "RateLimit-Reset".  The server MAY arbitrarily alter the "RateLimit-Reset" value between <del> subsequent requests eg. in case of resource saturation or to </del>  implement sliding window policies. 4. "RateLimit" values and the returned status code. Servers should be careful in returning "RateLimit" fields in <del> redirection responses (eg. 3xx status codes) because a low </del>  "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 important when quota-policies use a large "time-window". Under certain conditions, a server MAY artificially lower "RateLimit" <del> field values between subsequent requests, eg. to respond to Denial of Service attacks or in case of resource saturation. </del>  Servers usually establish whether the request is in-quota before creating a response, so the RateLimit field values should be already The value of "RateLimit-Reset" is generated at response time: a client aware of a significant network latency MAY behave accordingly <del> and use other information (eg. the "Date" response header field, or </del>  otherwise gathered metrics) to better estimate the "RateLimit-Reset" moment intended by the server. This specification does not mandate a specific throttling behavior and implementers can adopt their preferred policies, including: <del> slowing down or preemptively backoff their request rate when </del>  approaching quota limits; consuming all the quota according to the exposed limits and then 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, <del> 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 </del>  window. Request:

Fix typos
I'm really sorry for the poor Camilleri :) Wu Ming's "Q" is really worth reading though URL(novel)
What, no Eco? :)
No warnings
There are six lines that are marked as too long.: It might make sense to break these into two lines: and add text saying "Shown on two lines for clarity" or something.
3 fixed ;)
NAME Can this be closed now?
Looks good - thanks for the literary recommendations; I already followed inspector Montalbano's deeds, but Q looks an interesting addition... if/whenever my son gives me some time to read! :smile:

Servers use quota mechanisms to avoid systems overload, to ensure an equitable distribution of computational resources or to enforce other  <ins> policies - e.g. monetization. </ins> A basic quota mechanism limits the number of acceptable requests in a  <ins> given time window, e.g. 10 requests per second. </ins> When quota is exceeded, servers usually do not serve the request  <ins> replying instead with a "4xx" HTTP status code (e.g. 429 or 403) or </ins> adopt more aggressive policies like dropping connections.  <ins> Quotas may be enforced on different basis (e.g. per user, per IP, per </ins> geographic area, ..) and at different levels.  For example, an user may be allowed to issue: count once requests like "/books/{id}"  <ins> count twice search requests like "/books?author=WuMing" </ins> so that we have the following counters inferred by the value of "RateLimit-Reset" at the moment of the reset, or  <ins> communicated out-of-band (e.g. in the documentation). </ins> Policies using multiple quota limits MAY be returned using multiple "quota-policy" items, like shown in the following two examples: The client MUST NOT assume that all its "service-limit" will be restored after the moment referenced by "RateLimit-Reset".  The server MAY arbitrarily alter the "RateLimit-Reset" value between  <ins> subsequent requests e.g. in case of resource saturation or to </ins> implement sliding window policies. 4. "RateLimit" values and the returned status code. Servers should be careful in returning "RateLimit" fields in  <ins> redirection responses (e.g. 3xx status codes) because a low </ins> "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 important when quota-policies use a large "time-window". Under certain conditions, a server MAY artificially lower "RateLimit"  <ins> field values between subsequent requests, e.g. to respond to Denial of Service attacks or in case of resource saturation. </ins> Servers usually establish whether the request is in-quota before creating a response, so the RateLimit field values should be already The value of "RateLimit-Reset" is generated at response time: a client aware of a significant network latency MAY behave accordingly  <ins> and use other information (e.g. the "Date" response header field, or </ins> otherwise gathered metrics) to better estimate the "RateLimit-Reset" moment intended by the server. This specification does not mandate a specific throttling behavior and implementers can adopt their preferred policies, including:  <ins> slowing down or preemptively back-off their request rate when </ins> approaching quota limits; consuming all the quota according to the exposed limits and then 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,  <ins> 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 </ins> window. Request:


<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:

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

<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:


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.

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

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.


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)

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!

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)


available in that moment.  Nonetheless servers MAY decide to send the "RateLimit" fields in a trailer section.  3.1. Servers are not required to return "RateLimit" fields in every

a server SHOULD be configurable so that it can provide with or without compliant clients have to use SFV parsers non-compliant / pre-existing clients can still process fields with quota-policy:off and be migrated in time. eg..
NAME to support lightweight/IoI devices, it's auspicable to always support the simple version :P
This document strives to formalize behavior that a lot of existing servers and clients already implement, i.e. the "3-integer (Limit/Remaining/Reset)" model of ratelimit HTTP headers. If existing clients already parse in some or all circumstances, isn't changing from an integer to a SFV list of integers a backwards-incompatible change? Of course, there's an upgrade path possible for existing clients: they should parse up to the first (if any) if they want to support both "old"-style and the in this RFC. But an upgrade path is not the same thing as backwards compatibility. In URL, NAME suggests the following as behavior an interoperable client could implement: It's precisely clients like this that would be affected by a change from integer-only to a SFV . Should we not call out that we are breaking compatibility with the de-facto standard in the wild?
While this is worth clarifying, the pseudocode is not a complete implementation, because the spec requires the field values to be validated before use. Eg.
I think the usage of SFV is orthogonal to our idea of backwards compatibility regarding this information. Of course many if not all existing clients will need to parse these headers differently because of this, but that is also the case with many of them parsing only the prefixed headers, or those that have slight variations in the names. The important thing is that once this parsing step is completed they should have at least the same basic information they used to have without the need to modify their rate limiting logic if they don't want to.
NAME I think it's worth calling out any change developers need to make to their parsing logic. That's considerably more difficult to change than just altering what headers to look for. Parsing a SFV header is non-trivial, especially compared to parsing an integer. I'm not pushing in this PR for any changes to the spec, aside for a clarifying note about what it takes to upgrade to this spec.
NAME sure, that's something to be aware of -- that said, I'd expect implementors to limit the changes to replacing the logic of a header parsing step with that from a SFV parsing library and end up with the same information - there are plenty such libraries out there by now. :)
If we have expectations for what implementors will do, those should typically be written in the document. :)
Agree, but... isn't that fully implied by specifying the fields follow the SFV RFC?
Related to . NAME can clarify/fix this?
PR replaced with
This is still a suggestion I haven't had enough time to really think through, but I thought it might be worth discussing. The document currently says that for Limit, the server can give back a list of all of the quota policies currently "in force". But for Remaining and Reset, the server can only give back (without resorting to nonstandard extensions) those values for the policies with the least remaining quota. It seems like it would be more "consistent" to instead have: Remaining and Reset both have a similar syntax to Limit, where you can give a list with w= parameters. (This is what I'm getting at in .) Or, Limit works like Remaining and Reset, where you only talk about the policy with the least remaining quota. We could still keep the w= parameter, just no list. This is what I'm proposing here. From talking offline, it seems the intention is that only the first value of Limit is actionable; the rest is just informative. I question whether we want to put information that isn't machine-actionable in an HTTP header/trailer. So what if we took and made it be a single SFV item, instead of a list of items? In the simplest case, this changes nothing. is equivalent either way. So the document would still be backwards compatible with most of what's out there, modulo the header name. would become just . Obviously, the case that needs refactoring is something like: Servers could either only mention the lowest window, or they could declare their other windows with a parameter? If we want to keep the informative notion of multiple windows standardized, we can even standardize the name and format of this parameter. Here's one possible idea:
We thought about it, but we decided to retain the current format to always have the three integers as mandatory actionable content. This avoids unnecessary complications for the average users while allowing advanced users to process fields with SFV using the first value as the key for the quota policy. The point is that we do not forbid to process the quota-policy, but we want that clients are not forced to do so. Does it make sense to you? Is there an use case not covered by the current setup?
Are you saying that you want the spec to be usable even if someone doesn't want to implement SFV? If so, how would you have people do that? By saying that clients can only parse up to the first character, if they don't want to validate SFV data? If so, I think this language may be a problem: URL By saying that is a list, but that implementations can ignore things past the first , I think the document would basically be saying that parse errors after can be silently dropped, and the data before the can be understood anyway. I'm pretty sure the SFV folks would object to that. From reading and implementing SFV, I get the strong sentiment that it is an all-or-nothing sort of spec. You need to buy into the fact that it dictates how parsing happens (and that implementations need to use an SFV library), or you need to give up using it entirely.
In https://ietf-wg-URL we state that they may be ignored wrt the client behavior, without mentioning the parsing. About being able to treat a field as a non-structured field, this can be useful to the discussion URL
According to this Mark's comment URL it's better to stick to SF, so the original point of NAME stays. when parsing quota-policies To ease the transition from old implementations, I would just suggest then that ratelimit providers SHOULD support a flag to enable/disable the providing of service-quota information.
If you want to weaken it further, you could say "MAY wish to provide" I don't know how widespread the transition would need to be nor how long. It's up to you.

available in that moment.  Nonetheless servers MAY decide to send the "RateLimit" fields in a trailer section. <ins> To ease the migration from existing rate limit headers, a server SHOULD be able to provide the "RateLimit-Limit" field even without the optional "quota-policy" section. </ins> 3.1. Servers are not required to return "RateLimit" fields in every


3. <del> A server MAY use one or more "RateLimit" response fields defined in this document to communicate its quota policies. </del>  The returned values refers to the metrics used to evaluate if the current request respects the quota policy and MAY not apply to

clarify fields dependencies according to the discussion in the issue -
It seems that it is not required to return all these 3 fields together. However, I was wondering if certain combinations would cause confusion. For example, if a server return RateLimit-Limit, RateLimit-Remaining but not RateLimit-Reset, such as: RateLimit-Limit: 10000, 10000;w=300 RateLimit-Remaining: 900 How would clients interpret the RateLimit-Remaining field without the RateLimit-Reset?
NAME Already fixed in and are REQUIRED; is RECOMMENDED. Can you please close if that fixes?
NAME sorry for missing the previous conversation. My take is RateLimit-Limit alone can be useful for clients. It tells the complete rate - quota in a time window. And clients can control its rate based on this field. RateLimit-Reset helps align the time window between the client and the server, but I think it can be optional. As long as client spread the load evenly, it does not need to know the reset. For example, if a server return RateLimit-Limit: 10000, 10000;w=300, that is about 33.3 RPS or 2,000 requests per min(assuming the quota unit is a request), clients can adopt it and stay below the limit. However, the problem is when RateLimit-Remaining appears without RateLimit-Reset, because it is technically not a rate number due to missing time window. To summarize my opinion - RateLimit-Reset is required when RateLimit-Remaining is specified; otherwise, RateLimit-Reset is optional. Thoughts?
NAME By design, RateLimit-Limit quota-policies are OPTIONAL and not actionable. The only actionable value of RateLimit-Limit is that is the first value. Without RateLimit-Reset, you cannot identify the current time-window because quota-policy are not actionable. In the above case, the correct response is This is the reason why RateLimit-Reset is REQUIRED
Thanks for closing NAME ! Feel free to provide further feedback since it's useful to double check the specs!
NAME wdyt on ? Do you think it could better clarify that quota-policies are optional? Thx++, R
I do agree that having both limit number and policies in the same field is a bit confusing. That is the reason I thought RateLimit-Limit could be actionable, but now I get that the policy is optional. Just look at this example you provided: RateLimit-Limit: 10000, 10000;w=300 RateLimit-Reset: 300 It seems to have duplicated information. I do understand the benefit of the extensibility in the Limit field, but it could get too complex too soon for clients to consume.
The spec to define header inter-dependencies and returning policies [x] Limit -> Reset [x] Limit, Remaining, Reset Do I have to always return all headers? No Do I have to expose all headers or I can only expose a subset? Limit,Reset are REQUIRED, Remaining is OPTIONAL Do we need to add some considerations on client implementation? Already present.
clarifies that clients MUST NOT assume a server always returns fields
Comment by Erik. In https://ietf-wg-URL You state ‘A server MAY use one or more "RateLimit" response fields defined in this document to communicate its quota policies.’ but it does not clearly define how they would be used in isolation or how a client should respond to a limited set of headers (other than discussed earlier above) My feeling is RateLimit-Limit can be optional and RateLimit-Remaining and RateLimit-Reset can be used as a pair. RateLimit-Reset would only have value in isolation if sent with a 429 response code, on other responses it would be meaningless.
It could also make sense to return Reset with other status codes such as and , so I think we don't really want to mandate a specific relation other than, at most, saying that unsuccessful requests (for a broad definition of those, possibly including and at a minimum) with this field are expected to be unsuccessful until that time elapses.
After a couple of years of adoption, my experience is the following: implementations use all 3 fields. Though theoretically one could just return and , I never found an implementation doing this :heavycheckmark: implementations don't know Remaining, and just return Limit and Reset with a fixed window (eg. 1 second). We can then recommend the following: Limit, Reset: MUST Remaining: SHOULD Since https://ietf-wg-URL I now think that we shouldn't mess with status codes. NAME if this sounds reasonable to you, I can provide a PR
Yes, it sounds good, thank you!

3.  <ins> A server uses the "RateLimit" response fields defined in this document to communicate its quota policies according to the following rules: "RateLimit-Limit" and "RateLimit-Reset" are REQUIRED; "RateLimit-Remaining" is RECOMMENDED. </ins> The returned values refers to the metrics used to evaluate if the current request respects the quota policy and MAY not apply to


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

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:

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


"coap://sensor1.example.com" and "coap://sensor2.example.com", and posted the very payload of the 6th request of section 5 of RFC6690. <del> Note that said content is in violation of the rule against relative references in presence of the anchor attribute; the server accepted it because no ambiguity is created in this particular case. </del> It demonstrates how absolute link targets stay unmodified, while relative ones are resolved:

Closes: URL See rationale there. Action if not commented on: merge
The proposal from last meeting about handling RC66900-vs-8288 needs to be implemented: Prescribe that the RD always send href in absolute form if anchor is present (things like can stay relative) Adapt all examples Update the illustrative appendix Describe motivation for the rule
Open questions: Will links-json follow what we discussed and have clear 8288-style resolution? (waiting for responses to ) Shall the rule for permissible data at registration be "no relative href when anchor is present" (clear and concise, but overly restrictive at or "no relative href when anchor is present and more absolute than the target" (verbose to describe, but less restrictive / doesn't produce collateral damage)? The current proposal acknowledges the problem when referring to "the payload of the 6th request of section 5 of..."; the appendix will also need to have its examples adapted further on that when it's decided.
The sharper variety of the rules can be phrased like this: (For RFC6690 documents), "If anchor is an absolute reference, the target reference must be absolute. If the anchor is a relative reference, the target can only be a relative reference if its takes the same ABNF alternative choice as the anchor's , or a choice listed earlier in the ABNF definition of in RFC 3986 -- unless anchor is of the form, in which case the target can not take the too but must be absolute or pick an earlier choice. (Figuratively speaking, the anchor can not be more absolute than the target)." Quite a mouthful just to keep allowing all examples of RFC6690 like in .. (The "bad" cases that cause ambiguity never showed up in any examples so far unless they were constructed on purpose to show the ambiguity.) I've pushed a version that includes the more restrictive variety to master to keep things flowing.
Revisiting this: fine-graned wording seems to be overkill, but so is ruling out common expressions in .well-known/core documents. Toning down to "SHOULD NOT contain statements that would cause ambiguity between RFC6690 and RFC8288 interpretation" in an upcoming pull request to close this issue. Hello links-json authors, there is a discrepancy between the Link Format described in RFC6690 and the Link header described in RFC8288 (formerly 5988bis). Take the example this line obtained from a resource : ;rel="x";anchor="http://external-host/" If this is sent in an RFC6690 document, it means ;rel="x";anchor="http://external-host/" but if it is sent in an RFC8288 header, it means ;rel="x";anchor="http://external-host/" On the formal side, this means that some statements can not be expressed in RFC6690 link format without knowledge of where the resource is served from. This is detrimental when describing links in an (esp. statically configured) collection to describe members using outside anchors. On the practical side, this leads to implementations doing the resolution wrong because none of the documents points out that there is a difference. On the social side, this results in many questions about link resolutions, and us CoRE people teaching ways that are not applicable to the rest of the web linking world. This point is especially relevant to links-json given it aims to be usable in the regular web world too. Please include a statement as to which of the interpretations is applied to JSON and CBOR link format documents. I strongly recommend to take up the interpretation of RFC8288. This does have effects on roundtrip-ability (the meaning of is inexpressable in RFC6690 documents, and needs to be converted to but retains the same semantics), but I still think that it is better to have that complexity in the converters than to carry on the mistakes[1] of the past into the next generation of content formats. Having a decision is also relevant to the Resource Directory draft (where this discussion comes from) because we need to either stay that we have to impose the same restrictions on JSON/CBOR documents as we do on RFC6690 ones ("no relative hrefs when anchor is present"), or we can recommend using JSON/CBOR link format because it can be used without worries. Best regards Christian [2]: My personal opinion of the origin of the discrepancy is that it was an honest mistake in reading 5988 back when 6690 was written (otherwise it would have been pointed out as a deliberate decision to deviate here) -- I made the same mistake myself[2] revisiting 5988. The newer 8288 does not allow for that interpretation any more. [1]: URL To use raw power is to make yourself infinitely vulnerable to greater powers. -- Bene Gesserit axiom

"coap://sensor1.example.com" and "coap://sensor2.example.com", and posted the very payload of the 6th request of section 5 of RFC6690.  It demonstrates how absolute link targets stay unmodified, while relative ones are resolved:


lookup mechanism for the resources that can be accessed on a group's multicast address (ie. no lookup will return links like "<coap://[ff35:30:2001:db8::1]/light>;..." for a group registered <del> with "con=copa://[ff35...]").  Such an additional lookup interface </del>  could be specified in an extension document. 7.3.

See issue discussion. Closes: URL Action if not commented on: merge.
copa -> coap
Thanks, fixed and merged.
Preparing for the IETF100 presentation I reviewed the role of groups in the RD, and given they are introduced with a focus on being discoverable multicast groups, I think I may have left that out of consideration when generalizing the lookup operations. There might be a class of desirable lookup operations that queries for resources on a multicast address: "Which resources are there in a multicast group?", the answer to which question would be typed links targetting a multicast address; in terms of -12's lookup examples: Req: GET /rd-lookup/XXX&rt="light" ;rt="light";anchor="coap://[ff35:30:2001:db8::1]", ;rt="light";anchor="coap://[ff35:30:2001:db8::1]" I'm unsure as to how that query should be formed exactly, and which links should be listed (those available on some devices? those on all?), but I think that those links should be in some form discoverable. Are such links something we want to make discoverable in an RD? Do we have enough information to decide which resources are accessible in a group? What metadata do we have on those links? (Eg. is it rt="light" if all nodes that have such a relative reference say it is?) If we can't or don't want supply those links (yet), is it justified to introduce groups as a "logical grouping of endpoints for the purpose of group communications", when all there is to it w/rt group communication is the ability to tell its multicast address in a group attribute? Strawman proposal assuming all links are valid candidates: Add an optional-to-implement lookup interface Group Resource (URL). It returns only links whose anchor was originally a relative reference, and re-interprets them once for each addressed group the link's endpoint is member of. Links that have become duplicate (as keyed by target, anchor and rel) are aggregated into one link, and their attribute lists are reduced to only those attributes common to all links in the aggregate. (rt=, if= and ct= attributes are not filtered out when they mismatch between the aggregated links, but are limited to their intersection value set.) The links are filtered after aggregation, and can match as aggregates, match their group or match an attribute present on all the endpoints whose links were aggregated.
Hi Chris, valid question. I seem to remember that in a distant past the links were specified with the group in the con parameter. That was then still possible. Add the links in the payload? FYI: RFC 7390 specifies names and MC addresses. chrysn schreef op 2017-11-12 06:46:
Hi Chris, not sure if I understood completely. A group lookup is like an ep lookup with multiple ep targets. The following seems a reasonable query to me: GET /rd-lookup/gp?con="coap://[ff35:30:2001:db8::1] which returns all eps with the specified MC address. The next query can be specified to find the resources of the returned eps. Seems perfectly OK to me; may be introduce such an example?
Hi Chris, a proposed addition to RD section 7.4 lookup examples Section 7.3 of RD says: “A search criterion matches an endpoint if it matches the endpoint itself or any of the groups it is contained in, and one on a resource if it matches the resource, the resource's endpoint, or any of the endpoint's groups.” Accordingly, the following example is proposed: Suppose a group light exists with two registrations, with endpoint names mylt1 and mylt2, where each registration contains one resource with rt=light. A resource lookup is wanted that requests the resources belonging to group lights. The RD returns the resources that are returned by the sequential invocation of the resource lookup of mylt1 and mylt2. Req: GET /rd-lookup/res?gp=light&rt=light Res: 2.05 Content <coap://[2001:db8:3::125]:61616/res/0;rt=”light”;ep=”myep1”;ct=40; anchor=”coap://[2001:db8:3:125]:61616”, <coap://[2001:db8:3::127]:61616/res/0;rt=”light”;ep=”myep2”;ct=40; anchor=”coap://[2001:db8:3:127]:61616”
The last example proposed already works. What I'm talking about in this issue is finding which resources there are that are, ie. which paths are reasonable to pack into a request going to a multicast address. As agreed in the last meeting, that issue can be solved by an additional document if the need arises. I'm writing a one-paragraph PR to add a statement about this, but the issue can be closed both by accepting that PR and by rejecting it with "no reason to say that, because any extension can be added later, no ned to enumerate them".
Note from far-later: If we accept the new-groups branch, this issue will be trivially solved as each group can be queried for its resources at and similar. All the open questions of how to know which resources are shared are resolved by that data being explicitly input into the RD.

lookup mechanism for the resources that can be accessed on a group's multicast address (ie. no lookup will return links like "<coap://[ff35:30:2001:db8::1]/light>;..." for a group registered  <ins> with "con=coap://[ff35...]").  Such an additional lookup interface </ins> could be specified in an extension document. 7.3.


expected that RDs will also be discoverable via other methods depending on the deployment. <del> Discovery of the RD URI paths is performed by sending either a multicast or unicast GET request to "/.well-known/core" and including a Resource Type (rt) parameter RFC6690 with the value "core.rd" in the query string.  Likewise, a Resource Type parameter value of "core.rd-lookup*" is used to discover the base URI for RD Lookup </del>  operations, and "core.gp" is used to discover the URI path for RD Group operations.  Upon success, the response will contain a payload with a link format entry for each RD function discovered, indicating YES (Unicast only) The following example shows an endpoint discovering an RD using this <del> interface, thus learning that the base RD resource is, in this example, at /rd and that the content-format delivered by the server hosting the resource is application/link-format (ct=40).  Note that it is up to the RD to choose its RD resource paths. </del>  The following example shows the way of indicating that a client may request alternate content-formats.  The Content-Format code attribute Content-Format 40 (application/link-format) indicated as well as a more application-specific content format (picked as 65225 in this example; this is in the experimental space, not an assigned value). <del> The base RD resource values /rd, /rd-lookup, and /rd-group are example values.  This server only implements some of the interfaces described in this document. </del>  5.3. <del> RD URI (mandatory).  This is the location of the RD, as obtained from discovery. </del>  Endpoint name (mandatory).  The endpoint name is an identifier that MUST be unique within a domain.  The maximum length of The following example shows an EP registering a group with the name "lights" which has two endpoints to an RD using this interface.  The <del> base location value /rd-group is an example RD location discovered in a request similar to example-discovery. </del>  6.2. 8.2. Access control SHOULD be performed separately for the RD <del> registration, Lookup, and group API base paths, as different endpoints may be authorized to register with an RD from those authorized to lookup endpoints from the RD.  Such access control SHOULD be performed in as fine-grained a level as possible.  For example access control for lookups could be performed either at the domain, endpoint or resource level. </del>  8.3. 10.2.2. LWM2M defines a registration interface based on the REST API, <del> described in rd.  The base URI path of the LWM2M Resource Directory is specified to be "/rd". </del>  LWM2M endpoints register object IDs, for example </1>, to indicate that a particular object type is supported, and register object

All URIs of RD APIs are discovered standalone, and no relative URI or path-appending is required any more. Therefore, the term "Base URIs" and the distinction between "rd-lookup-base" and "lookup-type" in the RD lookup API are obsolete. This has already been , and , if I understood his response correctly (which I'm unsure about, thus tagging this for review).
I'd consider toning down the default value recommendations a different issue; is it fine with you apart from that? (Note to self: I accidentally dropped the "res:= " parameter here; that's another topic and shouldn't go in that commit.)
There is still some weirdness here: The "URIs" here are still parameters for URI templates, not the actual URIs that will be used for accesses.
Good point. Going from to should address that, I'll update accordingly.
I've updated the pull request to address the comments, and fixed some oversights of mine. While the first commit has been modified, the changes should largely be review friendly in that the three last commits are the newly introduced ones for NAME template weirdness NAME "recommended" → "example" rewording and some more "base" occurrences I had missed, together with clearer naming of the "RD registration URI" instead of just "RD (base) URI" which might cause confusion with the "RD URIs" (the "RD lookup URIs" and the "RD group URI") in general.
Merged as agreed in last call.
It is argued that a recommended base path is not appropriate. At line 593: "the value /rd is recommended", should be: "the value /rd is an example value". Hello Peter, among those, I just happened to note that instead of (say) being advertised as URL (which would then have triggered string-appending "/ep" to it), the individual records are now advertised. Much appreciated; this makes implementation of resource trees smoother! (Actually I found an inconsistency of my implementation of -09, and looking it up, it was fixed in this version I had not read before). It does add one easily fixed quirx, however: In the lookup URI template, there's now /{+rd-looup-base}/{lookup-type}. Is that distinction still needed? The base can't be discovered now any more, so I'd say this now should be | URI Template: /{+type-lookup}{?d,...} | | type-lookup := RD lookup location (mandatory). Discovered for a given | type in .well-known/core by its resource type, where it SHOULD be | listed. The recommended value for this variable is: | "/rd-lookup/{type}". Mandatory to be present for types "ep" and | "res", optional for "d" and "gp". (Or maybe you they can stay "base URIs", but be many; that's only terminology then). I've gone through the rest of the document; "is used to discover the base URI for RD Lookup operations" would need to speak of "URIs". Sounds good now. The term "Simple directory discovery" was dropped from the descriptions but survived in 5.3.3; it should probably say "simple registration" there. Other notes (some on nitpicking level, but if we're at WGLC level I suppose that's OK): 5.2 mentions '"URL" is used to discover the base URI for RD group operations'. Shouldn't this be "URL"? (Unsure as not yet really familiar with all the groupcom things). 5.2 lists HTTP support but no HTTP response codes 5.2 first request/response example: needless quotes about a ct 5.3 example: The HTTP requester will probably want to set a con= too unless it actually sends the HTTP request from its port 80. 'The domain lookup returns every lookup domain with a base RD resource value (e.g. "/rd") encapsulated within angle brackets.' (and similarly the following group paragraph): This sounds contradictory to the example given later (which returns '<>;d="domain1"'), where nothing is encapsulated in the angle brackets. 9.3 "con" entry: Since the latest changes this should include "path" too. 10.1.2: In the requests from the CT, the domain parameter is given per-resource in the payload. Isn't that exclusively used as a query parameter in registration? Later in the group setup POST, the semicolons after the <> are missing in the payload, and the colon in 'coap//' in the con parameter, which has abundant quotation marks. 10.2: "./well-known/core" -> "/." I haven't updated my implementation yet, but don't see any trouble on that road. Looks good to me, all things considered. Best regards Christian To use raw power is to make yourself infinitely vulnerable to greater powers. -- Bene Gesserit axiom
Hi Christian, Thank for the feedback; see below. Christian Amsüss schreef op 2017-03-16 17:43: Good to read. URIs it will be; rd-lookup-base is also used later; and is an understandable concept. agreed. not yet. No opinion. see what the co-authors think. Correct; correct, again. good suggestions Yep, have to solve that one way or the other. mistakes come and go, in spite of github change it, thanks for looking at it. thanks again. there is also another instance; also here mistakes come and go. Many thanks, peter

expected that RDs will also be discoverable via other methods depending on the deployment.  <ins> Discovery of the RD registration URI path is performed by sending either a multicast or unicast GET request to "/.well-known/core" and including a Resource Type (rt) parameter RFC6690 with the value "core.rd" in the query string.  Likewise, a Resource Type parameter value of "core.rd-lookup*" is used to discover the URIs for RD Lookup </ins> operations, and "core.gp" is used to discover the URI path for RD Group operations.  Upon success, the response will contain a payload with a link format entry for each RD function discovered, indicating YES (Unicast only) The following example shows an endpoint discovering an RD using this  <ins> interface, thus learning that the RD registration resource is, in this example, at /rd, and that the content-format delivered by the server hosting the resource is application/link-format (ct=40).  Note that it is up to the RD to choose its RD resource paths. </ins> The following example shows the way of indicating that a client may request alternate content-formats.  The Content-Format code attribute Content-Format 40 (application/link-format) indicated as well as a more application-specific content format (picked as 65225 in this example; this is in the experimental space, not an assigned value).  <ins> The RD resource paths /rd, /rd-lookup, and /rd-group are example values.  This server only implements some of the interfaces described in this document. </ins> 5.3.  <ins> RD registration URI (mandatory).  This is the location of the RD, as obtained from discovery. </ins> Endpoint name (mandatory).  The endpoint name is an identifier that MUST be unique within a domain.  The maximum length of The following example shows an EP registering a group with the name "lights" which has two endpoints to an RD using this interface.  The  <ins> RD group path /rd-group is an example RD location discovered in a request similar to example-discovery. </ins> 6.2. 8.2. Access control SHOULD be performed separately for the RD  <ins> registration, Lookup, and group API paths, as different endpoints may be authorized to register with an RD from those authorized to lookup endpoints from the RD.  Such access control SHOULD be performed in as fine-grained a level as possible.  For example access control for lookups could be performed either at the domain, endpoint or resource level. </ins> 8.3. 10.2.2. LWM2M defines a registration interface based on the REST API,  <ins> described in rd.  The RD registration URI path of the LWM2M Resource Directory is specified to be "/rd". </ins> LWM2M endpoints register object IDs, for example </1>, to indicate that a particular object type is supported, and register object


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. >

NO <ins> For the second interaction triggered by the above, the endpoint takes the role of a server: </ins> RD -> EP GET


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

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.

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


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

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

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


The following response codes are defined for this interface: <del> 2.01 "Created" or 201 "Created".  The Location header option MUST be included in the response when a new registration resource is created.  This Location MUST be a stable identifier generated by the RD as it is used for all subsequent operations on this registration resource.  The registration resource location thus returned is for the purpose of updating the lifetime of the registration and for maintaining the content of the registered links, including updating and deleting links.  A registration with an already registered ep and d value pair responds with the same success code and Location as the original registration; the set of links registered with the endpoint is replaced with the links from the payload. </del>  4.00 "Bad Request" or 400 "Bad Request".  Malformed request. The following response codes are defined for this interface: <del> 2.01 "Created" or 201 "Created".  The Location header option MUST be returned in response to a successful group CREATE operation. This Location MUST be a stable identifier generated by the RD as it is used for delete operations of the group resource. </del>  4.00 "Bad Request" or 400 "Bad Request".  Malformed request.

…. Location-Path Location-Query has not been allowed so far but not forbidden either. This makes a decision against allowing a query component on grounds of potential conflict with query arguments added later at the Registration Update operation. The issue of URI templates that would need modification to do the right thing (become {&lt,con,...} for registration update rather than {?lt,con,...} if query is present) additionally weighs in favor of disallowing them. Various occurrences of "Location", "Location-Path" and "location" throughtout the document have been updated to use the correct term for the HTTP header, the CoAP option and the resulting URI, respectively. Closes: URL Submitting a "no Location-Query" proposal as announced on ; I happily make the opposite proposal based on this too if someone has an idea of how to deal with the conflict in the update operation and feels strongly torwards the other direction.
Hi Chris, what is location header? and and empty payload is returned after registration? I approve the restriction on query parameters cheerio, peter chrysn schreef op 2018-04-17 18:31:
The Location header is HTTP's equivalent to the Location-* (Location-Path, Location-Query) options of CoAP. Yes, but I think it's not explicit; can add that.
We currently don't say anything about a Location-Query that could be possible in a response to an initial registration (ie. whether the registration resource's URI can have a query parameter in it). Opinions are divided on whether we should have it at all, but if we want to have it, we need to do something about URI template weirdnesses. See discussion on Hello Peter, Carsten, hello Jim (responding cross-thread to the Location-Query point), (removing DNS-SD from the thread because I do not expect those topics to be particularly interesting there) On Fri, Apr 13, 2018 at 09:04:33AM +0200, peter van der Stok wrote: yes, as I am finally going thorough the existing issues and changes. The good reason is that we are using URI templates in the registration update operation: {+location}{?lt,con,extra-attrs*} While it should be intuitively obvious that for location="x://y/z?a=b" and lt="42", the produced URI is "x://y/z?a=b&lt=42", RFC6570 Section does not describe peeking back at what has been expanded to the left side, but prescribes a "?" to be used before the first value, so the produced URI would be "x://y/z?a=b?lt=42" (or possibly ?a=b%3Flt=42 but not ?a=b&lt=42). If I'm reading RFC6570 wrong here, Location-Path can be allowed and I'd be happy. Otherwise, we have to choose between using formal URI templates here (vs. saying that some query parameters can be appended) and allowing Location-Query. (Requiring anyone to understand ?foo=bar?baz=qux as two keyswould be madness so it's not an option.) link-json/-cbor is not helping with the issue of [1]. Whoever receives a link-format+json document and wants to follow a link given there needs to take the href and the anchor, and look up in RFC6690 Section 2.1, which is the very root of my misgivings about the situation. [1]: URL I don't know from a procedural PoV -- can we? And how far can that go? Best regards Christian I shouldn't have written all those tank programs. -- Kevin Flynn
There would not be a conflict with use in links descriptions, but still would be with extra parameters in a registration update. On those grounds I'll propose a text to rule out query parameters. Thanks Christian To use raw power is to make yourself infinitely vulnerable to greater powers. -- Bene Gesserit axiom

The following response codes are defined for this interface:  <ins> 2.01 "Created" or 201 "Created".  The Location-Path option or Location header MUST be included in the response.  This location MUST be a stable identifier generated by the RD as it is used for all subsequent operations on this registration resource.  The registration resource location thus returned is for the purpose of updating the lifetime of the registration and for maintaining the content of the registered links, including updating and deleting links.  A registration with an already registered ep and d value pair responds with the same success code and location as the original registration; the set of links registered with the endpoint is replaced with the links from the payload.  The location MUST NOT have a query or fragment component, as that could conflict with query parameters during the Registration Update operation.  Therefore, the Location-Query option MUST NOT be present in a successful response. </ins> 4.00 "Bad Request" or 400 "Bad Request".  Malformed request. The following response codes are defined for this interface:  <ins> 2.01 "Created" or 201 "Created".  The Location header or Location- Path option MUST be returned in response to a successful group CREATE operation.  This location MUST be a stable identifier generated by the RD as it is used for delete operations of the group resource.  As with the Registration operation, the location MUST NOT have a query or fragment component. </ins> 4.00 "Bad Request" or 400 "Bad Request".  Malformed request.


request as it would per registration.  The context of the registration is taken from the requesting server's URI.  The simple registration request interface is specified as follows: EP -> RD

See URL
The words server , directory server, and endpoint change meaning in the text dependent on the advance of the process. I find it confusing. Can we agree on the terminology "constrained endpoint" and "RD" and use that throughout this text?
Text updated, it now says "The Resource Directory MUST NOT..." and a note where it'd say "registree-ep" if is merged.
Merged this version. Jim would AFAIR have preferred the other way (execute then confirm) for semantic clarity, but I think that extremely-constrained ("no simultaneous exchanges") clients should be considered here as devices caring about return codes should do the full thing anyway.
Two of the current implementations have different behavior when it comes to simple registrations: Jim's sends an ACK, but belays the Success response to when the .well-known/core has been obtained. Mine sends Success anyway to acknowledge the EP's intent to register, and only logs an error if something later goes wrong. I think that Jim's is the better behavior; mine was motivated by consideration for clients that have a limited number of open exchanges (1), and might answer 5.03 for as long as they have outstanding CONs themselves. IMO we should either prescribe Jim's behavior or add a warning that the Success indication does not necessarily mean too much. Which would you prefer?
I prefer the success return, and having understood that things are out of control for the registering node. Option 2 involves keeping channels open, and for how long?, are retries possible? We are discussing here very low power, always sleeping nodes. Without a proxy their life is impossible anyway.
I've written conflicting PRs to either allow both () or prescribe immediate responses (). Either would be fine with me, "prescribe fetch-then-respond" does not sound like a consensus candidate from the comments. NAME and other authors: any preferences? I have a slight preference for accept-both.
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.

request as it would per registration.  The context of the registration is taken from the requesting server's URI. <ins> The Resource Directory MUST NOT query the endpoint's data before sending the response; this is to accomodate very limited endpoints. The success condition only indicates that the request was valid (ie. the passed parameters are valid per se), not that the link data could be obtained or parsed or was successfully registered into the RD. </ins> The simple registration request interface is specified as follows: EP -> RD


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

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?

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


filtering on groups would return a list of endpoints that are in the specified groups.  The lookup interface is specified as follows: Client -> RD

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.

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