[core] resource-directory-12: Request for reviews, annotated Change Log

[Christian Amsüss <[e-mail]>]

Hello CoRE working group,

On Mon, Oct 30, 2017 at 11:31:48AM -0700, [e-mail] wrote:
> A New Internet-Draft is available from the on-line Internet-Drafts directories.
> This draft is a work item of the Constrained RESTful Environments WG of the IETF.

With the document nearing completion, the authors would like to ask the
working group for reviews on the submitted draft.


Even though the document contains a change log, some changes were big
enough to deserve some more explanation, so we'd like to provide the WG
with some further notes and examples with the changelog entries:

----

   o  clarified where relative references are resolved, and how context
      and anchor interact

   o  new appendix on the interaction with RFCs 6690, 5988 and 3986

In particular, we now preserve the full resolved statements from Link
Format documents submitted to the RD, including the context and link
relations. This means that at resource lookup, clients need to be able
to understand the anchor= attribute.

Key example:

| Req: GET /rd-lookup/res?rt=temperature
|
| Res: 2.05 Content
| </sensors/temp>;rt="temperature";if="sensor";anchor="coap://[2001:db8::123]"

Example of a more complex original statement:

| Req: GET /rd-lookup/res?rel=describedby
|
| Res: 2.05 Content
| <http://example.com/temp-info.html>;rel="describedby";anchor="coap://[2001:db8::123]/sensors/temp"

----

   o  lookup interface: group and endpoint lookup return group and
      registration resources as link targets

This removes the need for a dedicated "list all groups/endpoints"
interface on the registration side.

Key example:

| Req: GET /rd-lookup/ep?et=power-node
|
| Res: 2.05 Content
| </rd/1234>;con="coap://[2001:db8::127]";ep="node5";et="power-node";ct="40";lt="600",
| </rd/4521>;con="coap://[2001:db8::129]";ep="node7";et="power-node";ct="40";lt="600";d="floor-3"

Note that as with all URIs in the RD, none of the concrete paths is
prescribed. Were a different implementation used, the same example could
be:

| Req: GET /~resdir/ep-lookup?et=power-node
|
| Res: 2.05 Content
| </~resdir/+reg/node5>;con="coap://[2001:db8::127]";ep="node5";et="power-node";lt="600",
| </~resdir/+reg/floor-3/node7>;con="coap://[2001:db8::129]";ep="node7";et="power-node";lt="600";d="floor-3"

This also allows an unambiguous syntax for putting registered endpoints
into groups:

| Req: POST /rd-group?gp=lights&con=coap://[ff35:30:2001:db8::1]
| Payload:
| </rd/1234>,</rd/4521>
|
| Res: 2.01 Created
| Location: /rd-group/12

----

   o  updated chapter "Finding a Resource Directory"; now distinguishes
      configuration-provided, network-provided and heuristic sources

Endpoints can be pre-configured to use a particular way to find their
RD, be it per IP uni-, multi- or anycast, DNS name or DNS-SD service.

Endpoints without explicit configuration look for an RD location that
comes with the network (eg. from SLAAC); in absence thereof, heuristics
for finding an RD are described (multicast discovery, ask the 6LBR).

----

Further changes:

   o  added Content Model section, including ER diagram

   o  removed domain lookup interface; domains are now plain attributes
      of groups and endpoints

   o  improved text on: atomicity, idempotency, lookup with multiple
      parameters, endpoint removal, simple registration

   o  updated LWM2M description

   o  lookup interface: search parameters work the same across all
      entities

   o  removed all methods that modify links in an existing registration
      (POST with payload, PATCH and iPATCH)

   o  removed plurality definition (was only needed for link
      modification)

   o  enhanced IANA registry text
   
   o  state that lookup resources can be observable

   o  More examples and improved text


Best regards
Christian

-- 
Christian Amsüss                      | Energy Harvesting Solutions GmbH
founder, system architect             | headquarter:
mailto:[e-mail]  | Arbeitergasse 15, A-4400 Steyr
tel:[phone]                | http://www.energyharvesting.at/
                                      | ATU68476614