Subject: [core] #414 (resource-directory): RESTful operation and link parameter changes

From: "core issue tracker" <[email-masked]>
Date: Wed, 13 Jul 2016 13:21:21 -0000

#414: RESTful operation and link parameter changes

 Hi,

 Some thought son the device registry. Started with making it more RESTful
 api, and expanded on the way to expressing more information as link
 parameters, and utilizing existing link parameters.
 1. change the URL shceme to be more RESTful, resources in URL path, not in
 query  parameters
 2. Proposal that lifetime, lt, is a new link-format parameter
 3. endpoint as URI in link-format payload for registration, in URL path
 segment for lookup (no ep parameter as in draft, ep was used as query
 parameter and link parameter)
 4. Collection (aka "domain") and group expressed as link parameters (no d,
 gp parameters as in draft)

 I also would like to see the "domain" parameter changed to more neutral
 collection. It forces clarity to the usage of domain in DNS vs as
 collection of endpoints in RD. The domain usage seemed confusing to me. It
 may or may not be a DNS domain in the end.

 Sincerely,
 - Lauri Piikivi

 # Link parameters
 ## Endpoint as the first target URI
 The first link in link-format is the endpoint name.
     <coap://node1/>;lt=600
 It can have domain
     <coap_tcp://node1.example.com/>

 Justification: endpoint is the base-link to the related resources in the
 endpoint. Expressing it as link is logical.

 Note, it an endpoint does not have static DNS entry or name, the RD can
 return in registration response a link, with explicit relation "host",
 that is the registered link to the endpoint. For example endpoint can
 learn the RD seen IP address in NAT environment, or RD can indicate back
 the DNS name for the endpoint.
 > Discussion
 > Endpoint can have multiple schemes, coap over UDP, coap
 > over DTLS, coap over TCP. Are these 1 registration (1
 > location) or do they need to be registered separately?
 > draft has ep as link parameter,  ch 7.1 page 25

 ## New link parameter: lifetime
 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.
 If resource link for an endpoint does not define own lt, the endpoint lt
 MUST be assumed.

 Justification: the lifetime is a parameter of the endpoint link, and for
 the resource links at the endpoint.
 > Discussion
 > Gives the possibility that resources may have different
 > lifetime than the endpoint host. Those can be updated in
 > RD

 ## Domain and group as Collection link parameter
 Collection and item link parameters are defined in RFC6573. Since the RD
 grouping of endpoints does not necessarily imply DNS domain usage, the
 logical grouping of endpoints into collections and groups is clearer. The
 relation can be also expressed in link parameters. Endpoint information,
 when retrieved from RD, can give the collection and group links for and
 endpoint. The links are URIs to the RD, with the relation parameter
 "collection"
 See https://tools.ietf.org/html/rfc6573#section-2.2
 Domain, as used in draft, is "collection". Group is a  expressed as
 "collection item"

 Groups are links, and can express the Name, Scheme, IP, Port. In
 registration the RD may return link-format document, and endpoint can
 learn additional information of the groups and collection it belongs to
 from that link-format.

 Most often the collection information is only used in the URL PATH to the
 endpoint. However, being able to read the registration data with
 collection information may help use cases for persistent storage of
 information and when reverse lookup from endpoint (or resoure) to the
 collections it belongs to are needed

 # Resource Directory Operations
 ##  Device Registration
 Method:  POST
 URI Template:  /rd/ep/EP_INSTANCE

 ## Registration path components
 rd/ep :=  RD Function Set path for endpoints (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.
 The mandatory segment "ep" is used to indicate endpoint related
 registration, update or query operations in the information hierarchy.

 EP_INSTANCE := The endpoint name (mandatory). The maximum length of this
 parameter is 63 bytes.

 After registration the endpoint name is an identifier that MUST be unique
 within a domain. RD service may return unique domain path and endpoint
 name in HTTP locator field, which MUST be used as the identifier from
 there on by the endpoint. An endpoint may get new locator in registration
 (for example if an endpoint resets and performs registration anew, while
 the old regstration is still valid for lifetime)

 ## Registration payload
 All other data, including context (link) are given in payload.

 ## Examples
 The following example shows an endpoint with the name "node1" registering
 two resources to an RD using this interface.  Context, scheme, authority
 and port is given as a link with the new lifetime parameter.

      Req: POST coap://rd.example.com/rd/ep/node1
      Content-Format: 40
      Payload:
      <coap://node1.example.com:5683">;lt=600
      </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
      </sensors/light>;ct=41;rt="light-lux";if="sensor"

      Res: 2.01 Created
      Location: /rd/ep/node1

 Device name is not unique, and the created resource for the device is
 named by the RD and device is found from path /ep/node1_1. Device does not
 have a domain name, so the RD acting as proxy inserts own context
 information to the registration

      Req: POST /rd/ep/node1 HTTP/1.1
      Host : example.com
      Content-Type: application/link-format
      Payload:
      <coap://node1.example.com:5683">;lt=600
      </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
      </sensors/light>;ct=41;rt="light-lux";if="sensor"

      Res: 201 Created
      Location: /rd/ep/node1_1

  Further references to the device MUST use the location /ep/node1_1

 ##  Registration Update

 URI Template:  /{+location}

 URI Template Variables:
 location :=  This is the Location path returned by the RD as a result of a
 successful earlier registration.

 P
 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. lt is kept as variable as it is not a
 hierarchical part of resource name

      Req: PATCH /rd/ep/node1_1

      Res: 2.04 Changed

 With explicit lt parameter

      Req: PATCH /rd/ep/node1_1?lt=600

      Res: 2.04 Changed

 ##  Registration Change

 The following example shows an endpoint updating its registration  with a
 new  context, changing an existing link, and adding a new link using this
 interface. Lifetime is updated as another call.  With the initial
 registration the client set the following values:
 o  lifetime (lt)=500
 o  context base-link=coap://local-proxy-old.example.com:5683
 o  resource= </sensors/temp>;ct=41;rt="foobar";if="sensor"

      Req: PATCH /rd/ep/node1
      Content-Format: 40
      Payload:
      <coap://local-proxy.example.com:5683">;lt=1200
      </sensors/temp>;ct=41;rt="temperature-f";if="core.s core.p custom-
 sensor",
      </sensors/door>;ct=41;rt="door";if="core.s custom-sensor"

      Res: 2.04 Changed

 # Resource Lookup

 ## General on the URL format
 URI Template may have domain. High level hierarchy is

   **rd-lookup-base/collection/group/endpoint/resource/interface**

 In shorter format, which SHOULD be supported the hierarchy is expressed as

   **rdlu/c/gp/ep/res/inf**

 With the formalization work for interfaces, they are raised to explicit
 parts of the information hierarchy.

 ## lookups to logical collections
 These lookups return links to RD logical collections. A  client must
 further query the RD for a list of endpoints in the logical collection

 These queries return a list of logical collections in the RD (links to RD
 with parameter rel="collection")

 ### lookup endpoint types, resource types and interface types
     Req /rdlu/rt/

 Returns a list of link-formats, to different resource types known by the
 RD
     Resp
     </rdlu/rt/temperature>
     </rdlu/rt/door>

     Req /rdlu/et/
     Resp
     </rdlu/et/power-node>
     </rdlu/et/movement-detectors>

     Req /rdlu/if/
     Resp
     </rdlu/if/core.s>
     </rdlu/if/core.a>
     </rdlu/if/custom-sensor>

 Further call to e.g. /rdlu/rt/door/ or /rdlu/if/core.s/ would return a
 list of endpoint links that have registered that resource type

 ###lookup all collections (formerly "domains")

      /rdlu/c/

 Returns EITHER a list of groups in the collection (links to RD with
 parameter rel="collection item") OR links to endpoints

 >Discussion
 > it is not possible to have a collection with direct
 > children of groups and endpoints both

 ## lookup endpoints
 As the endpoint is the host of resources, queries to path segment ep and
 lower (/ep, /ep/INSTANCE/res, ep/INSTANCE/res/INSTANCE/if) return links to
 endpoints, which a client can directly use to communicate with a endpoint.

 Note, that in practise the endpoint link can be to a proxy or gateway.

 > Discussion
 > Should the GW or proxy be expressed explicitly with a
 > VIA link relation for an endpoint? Assuming it it often
 > known by the RD that the system has a GW or proxy

 ###lookup all endpoints in collection COL_A
      /rdlu/c/COL_A/ep/

 It is expected that the common structure is more flat, and endpoints can
 be often listed directly, collection is optional.

 ###lookup all endpoints

       /rdlu/ep/

 ###lookup all resources in endpoint EP_A

      /rdlu/ep/EP_A/res/

 ###lookup all resource types in specific resource

      /rdlu/ep/EP_A/res/RES_3/if/

 ###lookup all resources in endpoint types HOME_SENSOR ???
      /rdlu/et/HOME_SENSOR/res

      /rdlu/c/COL_A/gp/ #lookup groups in collection
      /rdlu/c/rt/ # lookup resource types in collection

 ## URI Query part to lookups
  URI QUERY PART: ?page,count and count are query filters. They are used as
 query parameters, since they are not  resource selection but modify the
 amount of data shown for a path identifier.

 # Examples

 ## Logical group lookups
 The following example shows a client performing a lookup for endpoints in
 sepcific endpoint type:

     Req: GET /rdlu/et

     Res: 2.05 Content
     </power-node>;et="power-node";rel="collection",
     </actuator>;et="actuator";rel="collection"

 The following example shows a client performing a collection (previously
 domain) lookup:

     Req: GET /rdlu/c

     Res: 2.05 Content
     </collection1>;rel="collection",
     </collection2>;rel="collection"

 The following example shows a client performing a group lookup for groups
 in collection:

     Req: GET /rdlu/c/collection1/gp

     Res: 2.05 Content
     </lights1>;rel="collection item",
     </lights2>;rel="collection item"

 ## Endpoint lookups

 The following examples show endpoint queries for certain interface and
 resource type
      Req: GET /rdlu/if/core.s
      Res: 2.05 Content
      <coap://[FDFD::123]:61616/temp>;rt="temperature"

      Req: GET /rdlu/rt/temperature
      Res: 2.05 Content
      <coap://[FDFD::123]:61616/temp>;rt="temperature"

  The following example shows a client performing a lookup for endpoints in
 sepcific endpoint type:

      Req: GET /rdlu/et/power-node

      Res: 2.05 Content
      <coap://[FDFD::123]:61616>,
      <coap://[FDFD::123]:61616>

  The following example shows a client performing a lookup for all
 endpoints in a particular group:

      Req: GET /rdlu/gp/lights1/

      Res: 2.05 Content
      <coap://[FDFD::123]:61616>,
      <coap://[FDFD::124]:61616>

 ## Endpoint information query
 The following example shows a client performing a lookup for all groups an
 endpoint belongs to. To do this, the specific endpoint information is
 queried and collection and group information is parsed from the link-
 format. It is expected that this kind of reverse lookups are rare.

      Req: GET /rdlu/ep/node1

      Res: 2.05 Content
      Content-Format: 40
      Payload:
      <coap://node1.example.com:5683">;lt=1200
      </sensors/temp>;ct=41;rt="temperature-f";if="core.s core.p custom-
 sensor",
      </sensors/door>;ct=41;rt="door";if="core.s custom-sensor",
 <coap://rd.example.com/c/collection1>;rel="collection",<coap://rd.example.com/c/collection1/gp/group1>;rel="collection
 item",
 <coap://rd.example.com/c/collection1/gp/group2>;rel="collection item"

-- 
-------------------------+-------------------------------------------------
 Reporter:               |      Owner:  draft-ietf-core-resource-
  [email-masked]  |  [email-masked]
     Type:  protocol     |     Status:  new
  enhancement            |  Milestone:
 Priority:  major        |    Version:
Component:  resource-    |   Keywords:
  directory              |
 Severity:  -            |
-------------------------+-------------------------------------------------

Ticket URL: <https://trac.tools.ietf.org/wg/core/trac/ticket/414>
core <https://tools.ietf.org/core/>