Subject: [core] Resource Directory - Registration Update

From: Hannes Tschofenig <[email-masked]>
Date: Mon, 30 May 2016 21:50:16 +0200

Hi Michael, Hi all,

Here is the text from the RD draft about registration updates:

--------

5.3.  Update

   The update interface is used by an endpoint to refresh or update its
   registration with an RD.  To use the interface, the endpoint sends a
   POST request to the resource returned in the Location option in the
   response to the first registration.  An update MAY update the
   lifetime or context parameters if they have changed since the last
   registration or update.  Parameters that have not changed SHOULD NOT
   be included in an update.  Upon receiving an update request, the RD
   resets the timeout for that endpoint and updates the scheme, IP
   address and port of the endpoint (using the source address of the
   update, or the context parameter if present).

   An update MAY optionally add or replace links for the endpoint by
   including those links in the payload of the update as a CoRE Link
   Format document.  Including links in an update message greatly
   increases the load on an RD and SHOULD be done infrequently.  A link
   is replaced only if both the target URI and relation type match (see
   Section 10.1)

--------

Questions:

1) "Parameters that have not changed SHOULD NOT be included in an
update." Why is there is SHOULD NOT and not a MUST NOT? What is the
reason for sending parameters that have not changed?

Furthermore, since the second paragraph says that the update interface
not only allows parameters to change but also the payload it would be
good to be specific. I assume parameters and links contained in the
payload are meant.

2) There is a reference to Section 10.1, which is supposed to explain
the replacement procedure. Unfortunately, Section 10.1 does not contain
such a text.

3) The second paragraph says that the update may add or replace links.
How does this look like? There is no example. What about deleting a link?

Ciao
Hannes

---

From: Michael Koster <[email-masked]>
Date: Mon, 30 May 2016 13:11:30 -0700

Hi Hannes,

Thanks for the review. There is a new update of RD in the CoRE svn repository for review.

1. As an example, why should sending a lifetime parameter each time whether it changes or not be prohibited? It seems like it could simplify the client software in some cases and only uses the network more as a consequence. Is there a good reason to prohibit it and require a careful client? WOuld it be written into a conformance test or otherwise be detected?

1b. Yes, the registration parameters can be changed and also the link payload. The payload part is the same as your Q3 about add/replace links.

2. Section 10.1 is Endpoint Identification... I guess at one point someone thought it was relevant to the URI matching discussion. It doesn't make sense in the current context.

3. Add/Replace links with POST was meant to be a convenience for modification of the link payload using POST and combining with the registration refresh. POST is typically used to add items to a collection, even though in this case the items (links in the endpoint resource) aren't individually adressable as resources. Add/Replace operations are more suited to PATCH but we wanted to provide an alternate method in case PATCH isn't available (for example, OCF has not included PATCH but needs to modify link parameters, so they use POST)

I will clarify the text in section 5.3 about updating and replacing links, and I can add a couple of examples. 

Deleting a link must use PATCH, as there is (IMO) no acceptable way to signal delete with POST.

In the bigger picture, are there strong opinions about using POST to update/replace links or the fact the POST and PATCH may be 2 ways of performing some types of link modifications?

Thanks again!

Best regards,

Michael

> On May 30, 2016, at 12:50 PM, Hannes Tschofenig <[email-masked]> wrote:
> 
> Hi Michael, Hi all,
> 
> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core

---

From: Michael Koster <[email-masked]>
Date: Mon, 30 May 2016 16:42:04 -0700

Hi Hannes,

I made changes to adress these great points, and pushed a new version to the core svn repo. Please update accordingly. 

All folks interested, please review the draft in the svn repository. 
https://svn.tools.ietf.org/svn/wg/core/draft-ietf-core-resource-directory-xx.txt <https://svn.tools.ietf.org/svn/wg/core/draft-ietf-core-resource-directory-xx.txt>

Please submit requests for changes as tickets to the CoRE issue tracker.

Thanks!

Michael

> On May 30, 2016, at 1:11 PM, Michael Koster <[email-masked]> wrote:
> 
> Hi Hannes,
>

---

From: Hannes Tschofenig <[email-masked]>
Date: Tue, 31 May 2016 10:06:11 +0200

Hi Michael,

thanks for the super quick response.

I read through the document and I only have a few minor comments:

* Section Headings

I would use the following section headings:
 5.1 Initial/Full Registration
 5.2 Registration Update
 5.3 Registration Removal

* Section 5.2: Which of the three formats are mandatory to implement:
CoRE Link Format [RFC6690], JSON CoRE Link Format
(application/link-format+json), CBOR CoRE Link Format
(application/link-format+cbor) [I-D.ietf-core-links-json]

The first paragraph says that all parameters except the endpoint name
are optional but the bullet list says that the RD Function Set path is
mandatory.

   URI Template Variables:

      rd :=  RD Function Set path (mandatory).  This is the path of the
         RD Function Set, as obtained from discovery.  An RD SHOULD use
         the value "rd" for this variable whenever possible.

[Hannes] Whenever I see a 'SHOULD' I feel that the reader should be
given guidance on when this particular value is used and when not.

      ep :=  Endpoint name (mandatory).  The endpoint name is an
         identifier that MUST be unique within a domain.  The maximum
         length of this parameter is 63 bytes.

      d :=  Domain (optional).  The domain to which this endpoint
         belongs.  This parameter SHOULD be less than 63 bytes.

[Hannes] The endpoint name has a maximum length of 63 bytes but the
domain doesn't.

         Optional.  When this parameter is elided, the RD MAY associate
         the endpoint with a configured default domain.  The domain
         value is needed to export the endpoint to DNS-SD (see
         Section 9).
[Hannes] I would remove the word 'optional' here from the text since it
appears twice.

      et :=  Endpoint Type (optional).  The semantic type of the
         endpoint.  This parameter SHOULD be less than 63 bytes.
         Optional.

[Hannes] Same comment about the word 'optional'
 and also about the use of SHOULD.

      lt :=  Lifetime (optional).  Lifetime of the registration in
         seconds.  Range of 60-4294967295.  If no lifetime is included,
         a default value of 86400 (24 hours) SHOULD be assumed.

[Hannes] Wouldn't it be better to say "If no lifetime is included, a
default value of 86400 (24 hours) is assumed." The SHOULD feels
inappropriate since there is no default value in that case.

      con :=  Context (optional).  This parameter sets the scheme,
         address and port at which this server is available in the form
         scheme://host:port.  Optional.  In the absence of this
         parameter the scheme of the protocol, source IP address and
         source port of the register request are assumed.  This
         parameter is mandatory when the directory is filled by a third
         party such as an commissioning tool.

[Hannes] I would use the term 'conditional' here instead of 'optional'.
There is also this dangling 'optional' in the text.

* Section 5.3

Regarding "Parameters that have not changed SHOULD NOT be included in an
update." I would add "Adding parameters that have not changed only
increases the size of the message but does not have any other implications."

I am not sure what you are trying to say with this sentence:

" Parameters MUST be included as query parameters in an update operation
as in {registration}.
"

Regarding" Including links in an update message greatly increases the
load on an RD and SHOULD be done infrequently."
I am not sure what this really means. If the client has some new
resources it wants to add then what is the option? I am sure the client
is not just doing that for fun.

Regarding "A link is replaced only if both the target URI and relation
type match." I believe the term 'target URI' is undefined. My
understanding is that it is the </sensors/temp> from the example below.

Regarding "Links may be added, modified, and deleted using Update
Endpoint Links as described in Section 5.6." I would write "In addition
to the use of POST, as described in this section, there is an
alternative way to add, replace and even to delete links using PATCH.
The use of PATCH for updating a registration is described in Section 5.6."

Regarding the example in this context it is useful to describe what the
initial registration was at the RD before the update is sent. Here is my
proposal:

"
The following example shows an endpoint updating its registration with a
new lifetime and context, changing an existing link (by replacing the
old resource type with a new one), and adding a new link using this
interface. With the initial registration the client set the following
values:

 * lifetime (lt)=500
 * context (con)=coap://local-proxy-old.example.com:5683
 * resource= </sensors/temp>;ct=41;rt="foobar";if="sensor"

   Req: POST /rd/4521?lt=600&con="coap://local-proxy.example.com:5683"
   Content-Format: 40
   Payload:
   </sensors/temp>;ct=41;rt="temperature-f";if="sensor",
   </sensors/door>;ct=41;rt="door";if="sensor"

   Res: 2.04 Changed
"

Ciao
Hannes

On 05/31/2016 01:42 AM, Michael Koster wrote:
> Hi Hannes,
> 
> I made changes to adress these great points, and pushed a new version to
> the core svn repo. Please update accordingly. 
> 
> https://svn.tools.ietf.org/svn/wg/core/draft-ietf-core-resource-directory-xx.txt
> 
>> On May 30, 2016, at 1:11 PM, Michael Koster
>> <[email-masked] <mailto:[email-masked]>> wrote:
>>
>> Hi Hannes,
>>
>> 1. As an example, why should sending a lifetime parameter each time
>> whether it changes or not be prohibited? It seems like it could
>> simplify the client software in some cases and only uses the network
>> more as a consequence. Is there a good reason to prohibit it and
>> require a careful client? WOuld it be written into a conformance test
>> or otherwise be detected?
>>
>> 1b. Yes, the registration parameters can be changed and also the link
>> payload. The payload part is the same as your Q3 about add/replace links.
>>
>> 2. Section 10.1 is Endpoint Identification... I guess at one point
>> someone thought it was relevant to the URI matching discussion. It
>> doesn't make sense in the current context.
>>
>> 3. Add/Replace links with POST was meant to be a convenience for
>> modification of the link payload using POST and combining with the
>> registration refresh. POST is typically used to add items to a
>> collection, even though in this case the items (links in the endpoint
>> resource) aren't individually adressable as resources. Add/Replace
>> operations are more suited to PATCH but we wanted to provide an
>> alternate method in case PATCH isn't available (for example, OCF has
>> not included PATCH but needs to modify link parameters, so they use POST)
>>
>> I will clarify the text in section 5.3 about updating and replacing
>> links, and I can add a couple of examples.
>>
>> In the bigger picture, are there strong opinions about using POST to
>> update/replace links or the fact the POST and PATCH may be 2 ways of
>> performing some types of link modifications?
>>
>> Thanks again!
>>
>> Best regards,
>>
>> Michael
>>
>>> On May 30, 2016, at 12:50 PM, Hannes Tschofenig
>>> <[email-masked] <mailto:[email-masked]>> wrote:
>>>
>>> Hi Michael, Hi all,
>>>
>>> [email-masked] <mailto:[email-masked]>

---

From: Hannes Tschofenig <[email-masked]>
Date: Tue, 31 May 2016 11:10:37 +0200

Hi Michael,

I also wanted to provide a response to your questions below.

>> or otherwise be detected?

I made a small text proposal in my previous mail to address this issue.

>> payload. The payload part is the same as your Q3 about add/replace links.

Ok.

>> doesn't make sense in the current context.

Ok. Thanks for the text update.

>> links, and I can add a couple of examples.

Thanks for the update.

>> performing some types of link modifications?

The question for me is how important is it to make these updates in
general. In many cases a device will announce available resources with
the initial registration and will not update, add or remove resources.

For changing existing links, and for adding links there is POST (for an
update) and with re-sending an full registration again* there is also
the possibility to remove resources. So, the two mechanisms allow one to
re-create the same results but with a different degree of efficiency.

So, I am not entirely sure whether the PATCH will gain much.

Ciao
Hannes

PS: While Section 5.2 of
https://svn.tools.ietf.org/svn/wg/core/draft-ietf-core-resource-directory-xx.txt
says "The RD then creates a new
resource or updates an existing resource in the RD and returns its
location." it might be worthwhile to point out that this is a way to
remove previously registered resources (in comparison to remove the
entire registration altogether, which is described in Section 5.4).