[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00 draft-ietf-core-dynlink

CoRE                                                           Z. Shelby
Internet-Draft                                                       ARM
Intended status: Informational                                   M. Vial
Expires: January 7, 2017                              Schneider-Electric
                                                               M. Koster
                                                             SmartThings
                                                               C. Groves
                                                                  Huawei
                                                            July 6, 2016


     Dynamic Resource Linking for Constrained RESTful Environments
                      draft-groves-core-dynlink-00

Abstract

   For CoAP [RFC7252] Dynamic linking of state updates between
   resources, either on an endpoint or between endpoints, is defined
   with the concept of Link Bindings.  This document defines conditional
   observation attributes that work with Link Bindings or with simple
   CoAP Observe [RFC7641].

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on January 7, 2017.

Copyright Notice

   Copyright (c) 2016 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents



Shelby, et al.           Expires January 7, 2017                [Page 1]


Internet-Draft      Dynamic Resource Linking for CoRE          July 2016


   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Link Bindings and Observe Attributes  . . . . . . . . . . . .   3
     3.1.  Format  . . . . . . . . . . . . . . . . . . . . . . . . .   4
     3.2.  Binding methods . . . . . . . . . . . . . . . . . . . . .   5
     3.3.  Binding table . . . . . . . . . . . . . . . . . . . . . .   6
     3.4.  Resource Observation Attributes . . . . . . . . . . . . .   6
   4.  Interface Descriptions  . . . . . . . . . . . . . . . . . . .   7
     4.1.  Binding . . . . . . . . . . . . . . . . . . . . . . . . .   8
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .   9
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   9
   7.  Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .   9
   8.  Changelog . . . . . . . . . . . . . . . . . . . . . . . . . .   9
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   9
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .   9
     9.2.  Informative References  . . . . . . . . . . . . . . . . .  10
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  10

1.  Introduction

   IETF Standards for machine to machine communication in constrained
   environments describe a REST protocol and a set of related
   information standards that may be used to represent machine data and
   machine metadata in REST interfaces.  CoRE Link-format is a standard
   for doing Web Linking [RFC5988] in constrained environments.

   This document introduces the concept of a Link Binding, which defines
   a new link relation type to create a dynamic link between resources
   over which to exchange state updates.  Specifically, a Link Binding
   is a link for binding the state of 2 resources together such that
   updates to one are sent over the link to the other.  CoRE Link Format
   representations are used to configure, inspect, and maintain Link
   Bindings.  This document additionally defines a set of conditional
   Observe Attributes for use with Link Bindings and with the standalone
   CoRE Observe [RFC7641] method.

   Editor's note: This initial version is based on the text of I.D.ietf-
   core-interfaces-04.  Further work is needed around link bindings and
   extending the obeserve attributes with another use case that requires
   3 new optional attributes.



Shelby, et al.           Expires January 7, 2017                [Page 2]


Internet-Draft      Dynamic Resource Linking for CoRE          July 2016


2.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

   This specification requires readers to be familiar with all the terms
   and concepts that are discussed in [RFC5988] and [RFC6690].  This
   specification makes use of the following additional terminology:

   Link Binding:  A unidirectional logical link between a source
      resource and a destination resource, over which state information
      is synchronized.

3.  Link Bindings and Observe Attributes

   In a M2M RESTful environment, endpoints may directly exchange the
   content of their resources to operate the distributed system.  For
   example, a light switch may supply on-off control information that
   may be sent directly to a light resource for on-off control.
   Beforehand, a configuration phase is necessary to determine how the
   resources of the different endpoints are related to each other.  This
   can be done either automatically using discovery mechanisms or by
   means of human intervention and a so-called commissioning tool.  In
   this document the abstract relationship between two resources is
   called a link Binding.  The configuration phase necessitates the
   exchange of binding information so a format recognized by all CoRE
   endpoints is essential.  This document defines a format based on the
   CoRE Link-Format to represent binding information along with the
   rules to define a binding method which is a specialized relationship
   between two resources.  The purpose of a binding is to synchronize
   the content between a source resource and a destination resource.
   The destination resource MAY be a group resource if the authority
   component of the destination URI contains a group address (either a
   multicast address or a name that resolves to a multicast address).
   Since a binding is unidirectional, the binding entry defining a
   relationship is present only on one endpoint.  The binding entry may
   be located either on the source or the destination endpoint depending
   on the binding method.  The following table gives a summary of the
   binding methods described in more detail in Section 3.2.

          +---------+------------+-------------+---------------+
          | Name    | Identifier | Location    | Method        |
          +---------+------------+-------------+---------------+
          | Polling | poll       | Destination | GET           |
          | Observe | obs        | Destination | GET + Observe |
          | Push    | push       | Source      | PUT           |
          +---------+------------+-------------+---------------+



Shelby, et al.           Expires January 7, 2017                [Page 3]


Internet-Draft      Dynamic Resource Linking for CoRE          July 2016


3.1.  Format

   Since Binding involves the creation of a link between two resources,
   Web Linking and the CoRE Link-Format are a natural way to represent
   binding information.  This involves the creation of a new relation
   type, purposely named "boundto".  In a Web link with this relation
   type, the target URI contains the location of the source resource and
   the context URI points to the destination resource.  The Web link
   attributes allow a fine-grained control of the type of
   synchronization exchange along with the conditions that trigger an
   update.  This specification defines the attributes below:

           +--------------------+-----------+------------------+
           | Attribute          | Parameter | Value            |
           +--------------------+-----------+------------------+
           | Binding method     | bind      | xsd:string       |
           | Minimum Period (s) | pmin      | xsd:integer (>0) |
           | Maximum Period (s) | pmax      | xsd:integer (>0) |
           | Change Step        | st        | xsd:decimal (>0) |
           | Greater Than       | gt        | xsd:decimal      |
           | Less Than          | lt        | xsd:decimal      |
           +--------------------+-----------+------------------+

   Bind Method:  This is the identifier of a binding method which
      defines the rules to synchronize the destination resource.  This
      attribute is mandatory.

   Minimum Period:  When present, the minimum period indicates the
      minimum time to wait (in seconds) before sending a new
      synchronization message (even if it has changed).  In the absence
      of this parameter, the minimum period is up to the notifier.

   Maximum Period:  When present, the maximum period indicates the
      maximum time in seconds between two consecutive state
      synchronization messages (regardless if it has changed).  In the
      absence of this parameter, the maximum period is up to the
      notifier.  The maximum period MUST be greater than the minimum
      period parameter (if present).

   Change Step:  When present, the change step indicates how much the
      value of a resource SHOULD change before sending a new
      notification (compared to the value of the last notification).
      This parameter has lower priority than the period parameters, thus
      even if the change step has been fulfilled, the time since the
      last notification SHOULD be between pmin and pmax.

   Greater Than:  When present, Greater Than indicates the upper limit
      value the resource value SHOULD cross before sending a new



Shelby, et al.           Expires January 7, 2017                [Page 4]


Internet-Draft      Dynamic Resource Linking for CoRE          July 2016


      notification.  This parameter has lower priority than the period
      parameters, thus even if the Greater Than limit has been crossed,
      the time since the last notification SHOULD be between pmin and
      pmax.

   Less Than:  When present, Less Than indicates the lower limit value
      the resource value SHOULD cross before sending a new notification.
      This parameter has lower priority than the period parameters, thus
      even if the Less Than limit has been crossed, the time since the
      last notification SHOULD be between pmin and pmax.

3.2.  Binding methods

   A binding method defines the rules to generate the web-transfer
   exchanges that will effectively send content from the source resource
   to the destination resource.  The description of a binding method
   must define the following aspects:

   Identifier:  This is value of the "bind" attribute used to identify
      the method.

   Location:  This information indicates whether the binding entry is
      stored on the source or on the destination endpoint.

   REST Method:  This is the REST method used in the Request/Response
      exchanges.

   Conditions:  A binding method definition must state how the condition
      attributes of the abstract binding definition are actually used in
      this specialized binding.

   This specification supports 3 binding methods described below.

   Polling:  The Polling method consists of sending periodic GET
      requests from the destination endpoint to the source resource and
      copying the content to the destination resource.  The binding
      entry for this method MUST be stored on the destination endpoint.
      The destination endpoint MUST ensure that the polling frequency
      does not exceed the limits defined by the pmin and pmax attributes
      of the binding entry.  The copying process MAY filter out content
      from the GET requests using value-based conditions (e.g Change
      Step, Less Than, Greater Than).

   Observe:  The Observe method creates an observation relationship
      between the destination endpoint and the source resource.  On each
      notification the content from the source resource is copied to the
      destination resource.  The creation of the observation
      relationship requires the CoAP Observation mechanism [RFC7641]



Shelby, et al.           Expires January 7, 2017                [Page 5]


Internet-Draft      Dynamic Resource Linking for CoRE          July 2016


      hence this method is only permitted when the resources are made
      available over CoAP.  The binding entry for this method MUST be
      stored on the destination endpoint.  The binding conditions are
      mapped as query string parameters (see Section 3.4).

   Push:  When the Push method is assigned to a binding, the source
      endpoint sends PUT requests to the destination resource when the
      binding condition attributes are satisfied for the source
      resource.  The source endpoint MUST only send a notification
      request if the binding conditions are met.  The binding entry for
      this method MUST be stored on the source endpoint.

3.3.  Binding table

   The binding table is a special resource that gives access to the
   bindings on a endpoint.  A binding table resource MUST support the
   Binding interface defined in Section 4.1.  A profile SHOULD allow
   only one resource table per endpoint.

3.4.  Resource Observation Attributes

   When resource interfaces following this specification are made
   available over CoAP, the CoAP Observation mechanism [RFC7641] MAY be
   used to observe any changes in a resource, and receive asynchronous
   notifications as a result.  In addition, a set of query string
   parameters are defined here to allow a client to control how often a
   client is interested in receiving notifications and how much a
   resource value should change for the new representation to be
   interesting.  These query parameters are described in the following
   table.  A resource using an interface description defined in this
   specification and marked as Observable in its link description SHOULD
   support these observation parameters.  The Change Step parameter can
   only be supported on resources with an atomic numeric value.

   These query parameters MUST be treated as resources that are read
   using GET and updated using PUT, and MUST NOT be included in the
   Observe request.  Multiple parameters MAY be updated at the same time
   by including the values in the query string of a PUT.  Before being
   updated, these parameters have no default value.












Shelby, et al.           Expires January 7, 2017                [Page 6]


Internet-Draft      Dynamic Resource Linking for CoRE          July 2016


         +----------------+------------------+------------------+
         | Resource       | Parameter        | Data Format      |
         +----------------+------------------+------------------+
         | Minimum Period | /{resource}?pmin | xsd:integer (>0) |
         | Maximum Period | /{resource}?pmax | xsd:integer (>0) |
         | Change Step    | /{resource}?st   | xsd:decimal (>0) |
         | Less Than      | /{resource}?lt   | xsd:decimal      |
         | Greater Than   | /{resource}?gt   | xsd:decimal      |
         +----------------+------------------+------------------+

   Minimum Period:  When present, the minimum period indicates the
      minimum time to wait (in seconds) before sending a new
      synchronization message (even if it has changed).  In the absence
      of this parameter, the minimum period is up to the notifier.

   Maximum Period:  When present, the maximum period indicates the
      maximum time in seconds between two consecutive state
      synchronization messages (regardless if it has changed).  In the
      absence of this parameter, the maximum period is up to the
      notifier.  The maximum period MUST be greater than the minimum
      period parameter (if present).

   Change Step:  When present, the change step indicates how much the
      value of a resource SHOULD change before sending a new
      notification (compared to the value of the last notification).
      This parameter has lower priority than the period parameters, thus
      even if the change step has been fulfilled, the time since the
      last notification SHOULD be between pmin and pmax.

   Greater Than:  When present, Greater Than indicates the upper limit
      value the resource value SHOULD cross before sending a new
      notification.  This parameter has lower priority than the period
      parameters, thus even if the Greater Than limit has been crossed,
      the time since the last notification SHOULD be between pmin and
      pmax.

   Less Than:  When present, Less Than indicates the lower limit value
      the resource value SHOULD cross before sending a new notification.
      This parameter has lower priority than the period parameters, thus
      even if the Less Than limit has been crossed, the time since the
      last notification SHOULD be between pmin and pmax.

4.  Interface Descriptions

   This section defines REST interfaces for Binding table resources.
   The interface supports the link-format type.





Shelby, et al.           Expires January 7, 2017                [Page 7]


Internet-Draft      Dynamic Resource Linking for CoRE          July 2016


   The if= column defines the Interface Description (if=) attribute
   value to be used in the CoRE Link Format for a resource conforming to
   that interface.  When this value appears in the if= attribute of a
   link, the resource MUST support the corresponding REST interface
   described in this section.  The resource MAY support additional
   functionality, which is out of scope for this specification.
   Although this interface descriptions is intended to be used with the
   CoRE Link Format, it is applicable for use in any REST interface
   definition.

   The Methods column defines the methods supported by that interface,
   which are described in more detail below.

      +-----------+----------+-------------------+-----------------+
      | Interface | if=      | Methods           | Content-Formats |
      +-----------+----------+-------------------+-----------------+
      |   Binding | core.bnd | GET, POST, DELETE | link-format     |
      +-----------+----------+-------------------+-----------------+

4.1.  Binding

   The Binding interface is used to manipulate a binding table.  A
   request with a POST method and a content format of application/link-
   format simply appends new bindings to the table.  All links in the
   payload MUST have a relation type "boundTo".  A GET request simply
   returns the current state of a binding table whereas a DELETE request
   empties the table.

   The following example shows requests for adding, retrieving and
   deleting bindings in a binding table.


   Req: POST /bnd/ (Content-Format: application/link-format)
   <coap://sensor.example.com/s/light>;
     rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"
   Res: 2.04 Changed

   Req: GET /bnd/
   Res: 2.05 Content (application/link-format)
   <coap://sensor.example.com/s/light>;
     rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"

   Req: DELETE /bnd/
   Res: 2.04 Changed







Shelby, et al.           Expires January 7, 2017                [Page 8]


Internet-Draft      Dynamic Resource Linking for CoRE          July 2016


5.  Security Considerations

   An implementation of a client needs to be prepared to deal with
   responses to a request that differ from what is specified in this
   document.  A server implementing what the client thinks is a resource
   with one of these interface descriptions could return malformed
   representations and response codes either by accident or maliciously.
   A server sending maliciously malformed responses could attempt to
   take advantage of a poorly implemented client for example to crash
   the node or perform denial of service.

6.  IANA Considerations

   The "binding" interface description types requires registration.

   The new link relations type "boundto" requires registration.

7.  Acknowledgments

   Acknowledgement is given to colleagues from the SENSEI project who
   were critical in the initial development of the well-known REST
   interface concept, to members of the IPSO Alliance where further
   requirements for interface types have been discussed, and to Szymon
   Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have
   provided useful discussion and input to the concepts in this
   document.

8.  Changelog

   Initial Version 00

   o  This initial version is based on the text regarding the dynamic
      linking functionality in I.D.ietf-core-interfaces-05.

   o  The WADL description has been dropped in favour of a thorough
      textual description of the REST API.

9.  References

9.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.






Shelby, et al.           Expires January 7, 2017                [Page 9]


Internet-Draft      Dynamic Resource Linking for CoRE          July 2016


   [RFC5988]  Nottingham, M., "Web Linking", RFC 5988,
              DOI 10.17487/RFC5988, October 2010,
              <http://www.rfc-editor.org/info/rfc5988>.

   [RFC6690]  Shelby, Z., "Constrained RESTful Environments (CoRE) Link
              Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
              <http://www.rfc-editor.org/info/rfc6690>.

9.2.  Informative References

   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252,
              DOI 10.17487/RFC7252, June 2014,
              <http://www.rfc-editor.org/info/rfc7252>.

   [RFC7641]  Hartke, K., "Observing Resources in the Constrained
              Application Protocol (CoAP)", RFC 7641,
              DOI 10.17487/RFC7641, September 2015,
              <http://www.rfc-editor.org/info/rfc7641>.

Authors' Addresses

   Zach Shelby
   ARM
   150 Rose Orchard
   San Jose  95134
   FINLAND

   Phone: +1-408-203-9434
   Email: zach.shelby@arm.com


   Matthieu Vial
   Schneider-Electric
   Grenoble
   FRANCE

   Phone: +33 (0)47657 6522
   Email: matthieu.vial@schneider-electric.com


   Michael Koster
   SmartThings
   665 Clyde Avenue
   Mountain View  94043
   USA

   Email: michael.koster@smartthings.com



Shelby, et al.           Expires January 7, 2017               [Page 10]


Internet-Draft      Dynamic Resource Linking for CoRE          July 2016


   Christian Groves
   Huawei
   Australia

   Email: Christian.Groves@nteczone.com














































Shelby, et al.           Expires January 7, 2017               [Page 11]


Html markup produced by rfcmarkup 1.122, available from https://tools.ietf.org/tools/rfcmarkup/