Subject: [core] Feedback on draft-ietf-core-resource-directory-11

From: Hauke Petersen <[email-masked]>
Date: Fri, 4 Aug 2017 17:21:45 +0200

Dear all,

Pekka Nikander and I implemented (parts of) draft-ietf-core-resource-directory-11 during a hackathon in Dagstuhl [1] last week.  We implemented both an RD server for node.js [2], including an integration to Node RED [3], as well as an RD client integrated into RIOT [4,5]. While doing this, we came across some points in the draft that were not quite clear to us and which could potentially be clarified.  Sorry if these are duplicates, but I could not find anything on the mailing list archive about these points.

Simple registration (Sections 5.3.1/5.3.2):
-------------------------------------------

1. How should a node (RD client) update its entries when using the simple registration sequence, as described in 5.3.2?  We assumed that the node simply repeats the sequence, as described in that section, but the draft could be more precise on that matter.

2. Is it correct that a node using the simple registration is not able to delete its RD entries actively? So, is the only choice to simply not update its entries and wait for expiration of the defined lifetime?  Or is the idea that the node registers with lt=60 (the minimum) and then waits for 60 seconds?

3. How should the RD respond, if the payload of the initial POST request is not empty?  Apparently there was in an earlier draft also the possibility that the POST request could contain the resources, but that was removed.  However, the current draft does not define how the RD should respond in the case there is any content.

4. Examples in Section 5.3.2: both `Req:` line comments seem wrong: shouldn't be the initial

       POST coap://rd.example.com/.well-known/core?lt=6000;ep=node1

    be marked as like `from EP to [ff02::1] (RD server)` and the second

       GET coap://[ff02::1]/.well-known/core

    request be something like `from RD server to EP (unicast)`?

Registration Update (Section 5.4.1):
------------------------------------

5. Should the registration update PUT instead of POST?  That is, upon normal registration the RD responds with a new link to the initial POST with 2.01 Created and a Location (Section 5.3).  Then the update updates the data at the location.  Should that be a PUT instead of POST, as it does not create a new URL?  If it indeed shall be a POST, then the draft should have some rationale for why.

For some discussion on similar matters, see e.g. [6].

Best,
Hauke

[1]https://www.dagstuhl.de/en/program/calendar/evhp/?semnr=17303
[2]https://github.com/Ell-i/coap-rd
[3]https://github.com/Ell-i/node-red-contrib-coap-rd
[4]https://github.com/RIOT-OS/RIOT/pull/7406
[5]https://github.com/RIOT-OS/RIOT/pull/7428
[6]https://stackoverflow.com/questions/630453/put-vs-post-in-rest

---

From: Michael Koster <[email-masked]>
Date: Fri, 4 Aug 2017 11:14:38 -0700

Hi Hauke,

Thank you for the comments, particularly on simple registration. I agree that we need to clarify some points.

More comments are in-line:

> On Aug 4, 2017, at 8:21 AM, Hauke Petersen <[email-masked]> wrote:
> 
> Dear all,
> 
Yes, that is the expected behavior. We imply that in the phrase "occasionally sends", but agree we should be more specific.

> 2. Is it correct that a node using the simple registration is not able to delete its RD entries actively? So, is the only choice to simply not update its entries and wait for expiration of the defi…
Yes, we should be explicit about how simple registration entries expire.

> 3. How should the RD respond, if the payload of the initial POST request is not empty?  Apparently there was in an earlier draft also the possibility that the POST request could contain the resourc…
We removed that option because we already have a way to upload links in the registration payload, per section 5.3 and didn't want to require another, though it would make sense from a REST API point of view. Should payloads be ignored or should an error be signalled? We don't require an RD to expose any registered links in its .well-known/core. I would tend toward signalling some kind of exception.

Probably would be worthwhile to point out that an RD would still create an endpoint registration resource when using simple registration, but there is no defined way for the device using simple registration to obtain the location information.

>   be marked as like `from EP to [ff02::1] (RD server)` and the second
The POST is from the device at [ff02::1] using simple registration to register an EP to the RD server

>   request be something like `from RD server to EP (unicast)`?

Yes, the GET is from the RD server to the device at [ff02::1] to obtain its links to register

We can clarify that the registering device is at [ff02::1] in this example.
> Registration Update (Section 5.4.1):
The reason for using POST is to provide the option of sending an empty payload, in order to update the registration lifetime (refresh) without re-sending the links.

Some early implementations used PUT for the refresh and deleted all of the links on refresh operations. The definition of PUT is to replace the contents of the resource, and the REST libraries would enforce that behavior. If this is an empty payload, than the result is an empty resource. Thus, we changed to POST. 

The definition of POST does not seem to exclude updates as well as create as the actual result is determined by the server (see RFC2616, section 9.5 https://tools.ietf.org/html/rfc2616 <https://tools.ietf.org/html/rfc2616> ), and we signal the correct interpretation in the response. The response to an initial registration is 2.01 Created, and the response to a refresh or update, also using POST, is 2.04 Changed. It depends on how you interpret the requirement for a "subordinate resource".

We believe that his conforms best to the intent and practice of REST API design. I will review the stackoverflow reference and comment further if it seems useful.

I will also look into your implementation as I am also considering a nodejs implementation of RD. Node-RED is another interesting system to integrate.

Thanks again!

Best regards,

Michael

> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core