draft-ietf-core-dynlink-00.txt   draft-ietf-core-dynlink-01.txt 
CoRE Working Group Z. Shelby CoRE Working Group Z. Shelby
Internet-Draft ARM Internet-Draft ARM
Intended status: Informational Z. Vial Intended status: Informational Z. Vial
Expires: April 22, 2017 Schneider-Electric Expires: May 1, 2017 Schneider-Electric
M. Koster M. Koster
SmartThings SmartThings
C. Groves C. Groves
Huawei Huawei
October 19, 2016 October 28, 2016
Dynamic Resource Linking for Constrained RESTful Environments Dynamic Resource Linking for Constrained RESTful Environments
draft-ietf-core-dynlink-00 draft-ietf-core-dynlink-01
Abstract Abstract
For CoAP [RFC7252] Dynamic linking of state updates between For CoAP [RFC7252] Dynamic linking of state updates between
resources, either on an endpoint or between endpoints, is defined resources, either on an endpoint or between endpoints, is defined
with the concept of Link Bindings. This document defines conditional with the concept of Link Bindings. This specification defines
observation attributes that work with Link Bindings or with simple conditional observation attributes that work with Link Bindings or
CoAP Observe [RFC7641]. with CoAP Observe [RFC7641].
Editor's note:
o The git repository for the draft is found at https://github.com/
core-wg/dynlink
o Examples need to be added.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 22, 2017. This Internet-Draft will expire on May 1, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Link Bindings and Observe Attributes . . . . . . . . . . . . 3 3. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Format . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Binding Methods . . . . . . . . . . . . . . . . . . . . . 4
3.2. Binding Methods . . . . . . . . . . . . . . . . . . . . . 5 3.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 5
3.3. Binding Table . . . . . . . . . . . . . . . . . . . . . . 6 3.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 5
3.4. Resource Observation Attributes . . . . . . . . . . . . . 6 3.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 5
4. Interface Descriptions . . . . . . . . . . . . . . . . . . . 8 3.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 5
4.1. Binding . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.3. Binding Attributes . . . . . . . . . . . . . . . . . . . 6
5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 3.3.1. Bind Method (bind) . . . . . . . . . . . . . . . . . 6
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 3.3.2. Minimum Period (pmin) . . . . . . . . . . . . . . . . 6
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 3.3.3. Maximum Period (pmax) . . . . . . . . . . . . . . . . 6
8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.3.4. Change Step (st) . . . . . . . . . . . . . . . . . . 7
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.3.5. Greater Than (gt) . . . . . . . . . . . . . . . . . . 7
9.1. Normative References . . . . . . . . . . . . . . . . . . 10 3.3.6. Less Than (lt) . . . . . . . . . . . . . . . . . . . 7
9.2. Informative References . . . . . . . . . . . . . . . . . 10 3.3.7. Attribute Interactions . . . . . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 4. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Binding Interface Description . . . . . . . . . . . . . . 8
4.2. Resource Observation Attributes . . . . . . . . . . . . . 9
5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
6.1. Interface Description . . . . . . . . . . . . . . . . . . 11
6.2. Link Relations Type . . . . . . . . . . . . . . . . . . . 11
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12
8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 12
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 13
9.1. Normative References . . . . . . . . . . . . . . . . . . 13
9.2. Informative References . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction 1. Introduction
IETF Standards for machine to machine communication in constrained IETF Standards for machine to machine communication in constrained
environments describe a REST protocol and a set of related environments describe a REST protocol and a set of related
information standards that may be used to represent machine data and information standards that may be used to represent machine data and
machine metadata in REST interfaces. CoRE Link-format is a standard machine metadata in REST interfaces. CoRE Link-format is a standard
for doing Web Linking [RFC5988] in constrained environments. for doing Web Linking [RFC5988] in constrained environments.
This document introduces the concept of a Link Binding, which defines This specification introduces the concept of a Link Binding, which
a new link relation type to create a dynamic link between resources defines a new link relation type to create a dynamic link between
over which to exchange state updates. Specifically, a Link Binding resources over which to exchange state updates. Specifically, a Link
is a link for binding the state of 2 resources together such that Binding is a link for binding the state of 2 resources together such
updates to one are sent over the link to the other. CoRE Link Format that updates to one are sent over the link to the other. CoRE Link
representations are used to configure, inspect, and maintain Link Format representations are used to configure, inspect, and maintain
Bindings. This document additionally defines a set of conditional Link Bindings. This specification additionally defines a set of
Observe Attributes for use with Link Bindings and with the standalone conditional Observe Attributes for use with Link Bindings and with
CoRE Observe [RFC7641] method. 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.
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this specification are to be interpreted as described
[RFC2119]. in [RFC2119].
This specification requires readers to be familiar with all the terms This specification requires readers to be familiar with all the terms
and concepts that are discussed in [RFC5988] and [RFC6690]. This and concepts that are discussed in [RFC5988] and [RFC6690]. This
specification makes use of the following additional terminology: specification makes use of the following additional terminology:
Link Binding: A unidirectional logical link between a source Link Binding: A unidirectional logical link between a source
resource and a destination resource, over which state information resource and a destination resource, over which state information
is synchronized. is synchronized.
3. Link Bindings and Observe Attributes State Synchronization: Depending on the binding method (Polling,
Observe, Push) different REST methods may be used to synchronize
the resource values between a source and a destination. The
process of using a REST method to achieve this is defined as
"State Synchronization". The endpoint triggering the state
synchronization is the synchronization initiator.
3. Link Bindings
In a M2M RESTful environment, endpoints may directly exchange the In a M2M RESTful environment, endpoints may directly exchange the
content of their resources to operate the distributed system. For content of their resources to operate the distributed system. For
example, a light switch may supply on-off control information that example, a light switch may supply on-off control information that
may be sent directly to a light resource for on-off control. may be sent directly to a light resource for on-off control.
Beforehand, a configuration phase is necessary to determine how the Beforehand, a configuration phase is necessary to determine how the
resources of the different endpoints are related to each other. This resources of the different endpoints are related to each other. This
can be done either automatically using discovery mechanisms or by can be done either automatically using discovery mechanisms or by
means of human intervention and a so-called commissioning tool. In means of human intervention and a so-called commissioning tool. In
this document the abstract relationship between two resources is this specification the abstract relationship between two resources is
called a link Binding. The configuration phase necessitates the called a link Binding. The configuration phase necessitates the
exchange of binding information so a format recognized by all CoRE exchange of binding information so a format recognized by all CoRE
endpoints is essential. This document defines a format based on the endpoints is essential. This specification defines a format based on
CoRE Link-Format to represent binding information along with the the CoRE Link-Format to represent binding information along with the
rules to define a binding method which is a specialized relationship rules to define a binding method which is a specialized relationship
between two resources. The purpose of a binding is to synchronize between two resources. The purpose of a binding is to synchronize
the content between a source resource and a destination resource. the content between a source resource and a destination resource.
The destination resource MAY be a group resource if the authority The destination resource MAY be a group resource if the authority
component of the destination URI contains a group address (either a component of the destination URI contains a group address (either a
multicast address or a name that resolves to a multicast address). multicast address or a name that resolves to a multicast address).
Since a binding is unidirectional, the binding entry defining a Since a binding is unidirectional, the binding entry defining a
relationship is present only on one endpoint. The binding entry may relationship is present only on one endpoint. The binding entry may
be located either on the source or the destination endpoint depending be located either on the source or the destination endpoint depending
on the binding method. The following table gives a summary of the on the binding method.
binding methods described in more detail in Section 3.2
3.1. Binding Methods
A binding method defines the rules to generate the web-transfer
exchanges that synchronize state between source and destination
resources. By using REST methods content is sent from the source
resource to the destination resource.
The following table gives a summary of the binding methods defined in
this specification.
+---------+------------+-------------+---------------+ +---------+------------+-------------+---------------+
| Name | Identifier | Location | Method | | Name | Identifier | Location | Method |
+---------+------------+-------------+---------------+ +---------+------------+-------------+---------------+
| Polling | poll | Destination | GET | | Polling | poll | Destination | GET |
| | | | | | | | | |
| Observe | obs | Destination | GET + Observe | | Observe | obs | Destination | GET + Observe |
| | | | | | | | | |
| Push | push | Source | PUT | | Push | push | Source | PUT |
+---------+------------+-------------+---------------+ +---------+------------+-------------+---------------+
Table 1: Binding Method Summary Table 1: Binding Method Summary
3.1. Format The description of a binding method must define the following
aspects:
Identifier: This is the 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.
The binding methods are described in more detail below.
3.1.1. 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 based on the Change Step, Less Than, Greater
Than attributes).
3.1.2. 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] 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 4.2).
3.1.3. 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.2. Link Relation
Since Binding involves the creation of a link between two resources, Since Binding involves the creation of a link between two resources,
Web Linking and the CoRE Link-Format are a natural way to represent Web Linking and the CoRE Link-Format are a natural way to represent
binding information. This involves the creation of a new relation binding information. This involves the creation of a new relation
type, purposely named "boundto". In a Web link with this relation type, named "boundto". In a Web link with this relation type, the
type, the target URI contains the location of the source resource and target URI contains the location of the source resource and the
the context URI points to the destination resource. The Web link context URI points to the destination resource.
attributes allow a fine-grained control of the type of
synchronization exchange along with the conditions that trigger an 3.3. Binding Attributes
update. This specification defines the attributes below:
Web link attributes allow a fine-grained control of the type of state
synchronization along with the conditions that trigger an update.
This specification defines the attributes below:
+--------------------+-----------+------------------+ +--------------------+-----------+------------------+
| Attribute | Parameter | Value | | Attribute | Parameter | Value |
+--------------------+-----------+------------------+ +--------------------+-----------+------------------+
| Binding method | bind | xsd:string | | Binding method | bind | xsd:string |
| | | | | | | |
| Minimum Period (s) | pmin | xsd:integer (>0) | | Minimum Period (s) | pmin | xsd:integer (>0) |
| | | | | | | |
| Maximum Period (s) | pmax | xsd:integer (>0) | | Maximum Period (s) | pmax | xsd:integer (>0) |
| | | | | | | |
| Change Step | st | xsd:decimal (>0) | | Change Step | st | xsd:decimal (>0) |
| | | | | | | |
| Greater Than | gt | xsd:decimal | | Greater Than | gt | xsd:decimal |
| | | | | | | |
| Less Than | lt | xsd:decimal | | Less Than | lt | xsd:decimal |
+--------------------+-----------+------------------+ +--------------------+-----------+------------------+
Table 2: Binding Attributes Summary Table 2: Binding Attributes Summary
Bind Method: This is the identifier of a binding method which 3.3.1. Bind Method (bind)
defines the rules to synchronize the destination resource. This
attribute is mandatory.
Minimum Period: When present, the minimum period indicates the This is the identifier of a binding method which defines the rules to
minimum time to wait (in seconds) before sending a new synchronize the destination resource. This attribute is mandatory.
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 3.3.2. Minimum Period (pmin)
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 When present, the minimum period indicates the minimum time to wait
value of a resource SHOULD change before sending a new (in seconds) before triggering a new state synchronization (even if
notification (compared to the value of the last notification). it has changed). In the absence of this parameter, the minimum
This parameter has lower priority than the period parameters, thus period is up to the synchronization initiator. The minimum period
even if the change step has been fulfilled, the time since the MUST be greater than zero otherwise the receiver MUST return a CoAP
last notification SHOULD be between pmin and pmax. error code 4.00 "Bad Request" (or equivalent).
Greater Than: When present, Greater Than indicates the upper limit 3.3.3. Maximum Period (pmax)
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 When present, the maximum period indicates the maximum time in
the resource value SHOULD cross before sending a new notification. seconds between two consecutive state synchronizations (regardless if
This parameter has lower priority than the period parameters, thus it has changed). In the absence of this parameter, the maximum
even if the Less Than limit has been crossed, the time since the period is up to the synchronization initiator. The maximum period
last notification SHOULD be between pmin and pmax. MUST be greater than zero and MUST be greater than the minimum period
parameter (if present) otherwise the receiver MUST return a CoAP
error code 4.00 "Bad Request" (or equivalent).
3.2. Binding Methods 3.3.4. Change Step (st)
A binding method defines the rules to generate the web-transfer When present, the change step indicates how much the value of a
exchanges that will effectively send content from the source resource resource SHOULD change before triggering a new state synchronization
to the destination resource. The description of a binding method (compared to the value of the previous synchronization). Upon
must define the following aspects: reception of a query including the st attribute the current value
(CurrVal) of the resource is set as the initial value (STinit). Once
the resource value differs from the STinit value (i.e. CurrVal >=
STinit + ST or CurrVal <= STint - ST) then a new state
synchronization occurs. STinit is then set to the state
synchronization value and new state synchronizations are based on a
change step against this value. The change step MUST be greater than
zero otherwise the receiver MUST return a CoAP error code 4.00 "Bad
Request" (or equivalent).
Identifier: This is value of the "bind" attribute used to identify Note: Due to the state synchronization based update of STint it may
the method. result in that resource value received in two sequential state
synchronizations differs by more than st.
Location: This information indicates whether the binding entry is 3.3.5. Greater Than (gt)
stored on the source or on the destination endpoint.
REST Method: This is the REST method used in the Request/Response When present, Greater Than indicates the upper limit value the
exchanges. resource value SHOULD cross before triggering a new state
synchronization. State synchronization only occurs when the resource
value exceeds the specified upper limit value. The actual resource
value is used for the synchronization rather than the gt value. If
the value continues to rise, no new state synchronizations are
generated as a result of gt. If the value drops below the upper
limit value and then exceeds the upper limit then a new state
synchronization is generated.
Conditions: A binding method definition must state how the condition 3.3.6. Less Than (lt)
attributes of the abstract binding definition are actually used in
this specialized binding.
This specification supports 3 binding methods described below: When present, Less Than indicates the lower limit value the resource
value SHOULD cross before triggering a new state synchronization.
State synchronization only occurs when the resource value is less
than the specified lower limit value. The actual resource value is
used for the synchronization rather than the lt value. If the value
continues to fall no new state synchronizations are generated as a
result of lt. If the value rises above the lower limit value and
then drops below the lower limit then a new state synchronization is
generated.
Polling: The Polling method consists of sending periodic GET 3.3.7. Attribute Interactions
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 Pmin, pmax, st, gt and lt may be present in the same query.
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]
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 If pmin and pmax are present in a query then they take precedence
endpoint sends PUT requests to the destination resource when the over the other parameters. Thus even if st, gt or lt are met, if
binding condition attributes are satisfied for the source pmin has not been exceeded then no state synchronization occurs.
resource. The source endpoint MUST only send a notification Likewise if st, gt or lt have not been met and pmax time has expired
request if the binding conditions are met. The binding entry for then state synchronization occurs. The current value of the resource
this method MUST be stored on the source endpoint. is used for the synchronization. If pmin time is exceeded and st, gt
or lt are met then the current value of the resource is synchronized.
If st is also included, a state synchronization resulting from pmin
or pmax updates STinit with the synchronized value.
3.3. Binding Table If gt and lt are included gt MUST be greater than lt otherwise an
error CoAP error code 4.00 "Bad Request" (or equivalent) MUST be
returned.
If st is included in a query with a gt or lt attribute then state
synchronizations occur only when the conditions described by st AND
gt or st AND gl are met.
4. Binding Table
The binding table is a special resource that gives access to the The binding table is a special resource that gives access to the
bindings on a endpoint. A binding table resource MUST support the bindings on a endpoint. A binding table resource MUST support the
Binding interface defined in Section 4.1. A profile SHOULD allow Binding interface defined below. A profile SHOULD allow only one
only one resource table per endpoint. resource table per endpoint.
3.4. Resource Observation Attributes 4.1. Binding Interface Description
This section defines a REST interface for Binding table resources.
The interface supports the link-format type.
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 description 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 REST methods supported by the
interface, which are described in more detail below.
+-----------+----------+-------------------+-----------------+
| Interface | if= | Methods | Content-Formats |
+-----------+----------+-------------------+-----------------+
| Binding | core.bnd | GET, POST, DELETE | link-format |
+-----------+----------+-------------------+-----------------+
Table 3: Binding Interface Description
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. Individual entries may be dreeleted from the
table by specifying the resource path in a DELETE request.
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/a/light
Res: 2.04 Changed
Req: DELETE /bnd/
Res: 2.04 Changed
Figure 1: Binding Interface Example
4.2. Resource Observation Attributes
When resource interfaces following this specification are made When resource interfaces following this specification are made
available over CoAP, the CoAP Observation mechanism [RFC7641] MAY be available over CoAP, the CoAP Observation mechanism [RFC7641] MAY be
used to observe any changes in a resource, and receive asynchronous used to observe any changes in a resource, and receive asynchronous
notifications as a result. In addition, a set of query string notifications as a result. In addition, a set of query string
parameters are defined here to allow a client to control how often a parameters are defined here to allow a client to control how often a
client is interested in receiving notifications and how much a client is interested in receiving notifications and how much a
resource value should change for the new representation to be resource value should change for the new representation to be
interesting. These query parameters are described in the following interesting. These query parameters are described in the following
table. A resource using an interface description defined in this table. A resource using an interface description defined in this
skipping to change at page 7, line 31 skipping to change at page 10, line 28
| | | | | | | |
| Maximum Period | /{resource}?pmax | xsd:integer (>0) | | Maximum Period | /{resource}?pmax | xsd:integer (>0) |
| | | | | | | |
| Change Step | /{resource}?st | xsd:decimal (>0) | | Change Step | /{resource}?st | xsd:decimal (>0) |
| | | | | | | |
| Less Than | /{resource}?lt | xsd:decimal | | Less Than | /{resource}?lt | xsd:decimal |
| | | | | | | |
| Greater Than | /{resource}?gt | xsd:decimal | | Greater Than | /{resource}?gt | xsd:decimal |
+----------------+------------------+------------------+ +----------------+------------------+------------------+
Table 3: Resource Observation Attribute Summary Table 4: Resource Observation Attribute Summary
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 Minimum Period: As per Section 3.3.2
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 Maximum Period: As per Section 3.3.3
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 Change Step: As per Section 3.3.4
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 Greater Than: As per Section 3.3.5
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 Less Than: As per Section 3.3.6
This section defines REST interfaces for Binding table resources. 5. Security Considerations
The interface supports the link-format type.
The if= column defines the Interface Description (if=) attribute An implementation of a client needs to be prepared to deal with
value to be used in the CoRE Link Format for a resource conforming to responses to a request that differ from what is specified in this
that interface. When this value appears in the if= attribute of a specification. A server implementing what the client thinks is a
link, the resource MUST support the corresponding REST interface resource with one of these interface descriptions could return
described in this section. The resource MAY support additional malformed representations and response codes either by accident or
functionality, which is out of scope for this specification. maliciously. A server sending maliciously malformed responses could
Although this interface descriptions is intended to be used with the attempt to take advantage of a poorly implemented client for example
CoRE Link Format, it is applicable for use in any REST interface to crash the node or perform denial of service.
definition.
The Methods column defines the methods supported by that interface, 6. IANA Considerations
which are described in more detail below.
+-----------+----------+-------------------+-----------------+ 6.1. Interface Description
| Interface | if= | Methods | Content-Formats |
+-----------+----------+-------------------+-----------------+
| Binding | core.bnd | GET, POST, DELETE | link-format |
+-----------+----------+-------------------+-----------------+
Table 4: Inteface Description The specification registers the "binding" CoRE interface description
link target attribute value as per [RFC6690].
4.1. Binding Attribute Value: binding
The Binding interface is used to manipulate a binding table. A Editor's note: RFC6690 actually indicates the use of core. for CoRE
request with a POST method and a content format of application/link- WG documents. Therefore it probably is more correct to register
format simply appends new bindings to the table. All links in the core.binding . However this may cause a problem for existing
payload MUST have a relation type "boundTo". A GET request simply implementations. One approach may be to register two attributes
returns the current state of a binding table whereas a DELETE request "binding" and "core.binding."
empties the table.
The following example shows requests for adding, retrieving and Description: The binding interface is used to manipulate a binding
deleting bindings in a binding table. table which describes the link bindings between source and
destination resources for the purposes of synchronizing their
content.
Req: POST /bnd/ (Content-Format: application/link-format) Reference: This specification. Note to RFC editor: please insert the
<coap://sensor.example.com/s/light>; RFC of this specification.
rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"
Res: 2.04 Changed
Req: GET /bnd/ Notes: None
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/ 6.2. Link Relations Type
Res: 2.04 Changed
Figure 1: Binding Interface Example This specification registers the new "bounto" link relation type as
per [RFC5988].
5. Security Considerations Relation Name: boundto
An implementation of a client needs to be prepared to deal with Description: The purpose of a boundto relation type is to indicate
responses to a request that differ from what is specified in this that there is a binding between a source resource and a
document. A server implementing what the client thinks is a resource destination resource for the purposes of synchronizing their
with one of these interface descriptions could return malformed content.
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 Reference: This specification. Note to RFC editor: please insert
the RFC of this specification.
The "binding" interface description types requires registration Notes: None
The new link relations type "boundto" requires registration. Application Data: None
7. Acknowledgements 7. Acknowledgements
Acknowledgement is given to colleagues from the SENSEI project who Acknowledgement is given to colleagues from the SENSEI project who
were critical in the initial development of the well-known REST were critical in the initial development of the well-known REST
interface concept, to members of the IPSO Alliance where further interface concept, to members of the IPSO Alliance where further
requirements for interface types have been discussed, and to Szymon requirements for interface types have been discussed, and to Szymon
Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have
provided useful discussion and input to the concepts in this provided useful discussion and input to the concepts in this
document. specification.
8. Changelog 8. Changelog
draft-ietf-core-dynlink-01
o General: The term state synchronization has been introduced to
describe the process of synchronization between destination and
source resources.
o General: The document has been restructured the make the
information flow better.
o Clause 3.1: The descriptions of the binding attributes have been
updated to clarify their usage.
o Clause 3.1: A new clause has been added to discuss the
interactions between the resources.
o Clause 3.4: Has been simplified to refer to the descriptions in
3.1. As the text was largely duplicated.
o Clause 4.1: Added a clarification that individual resources may be
removed from the binding table.
o Clause 6: Formailised the IANA considerations.
draft-ietf-core-dynlink Initial Version 00: draft-ietf-core-dynlink Initial Version 00:
o This is a copy of draft-groves-core-dynlink-00 o This is a copy of draft-groves-core-dynlink-00
draft-groves-core-dynlink Draft Initial Version 00: draft-groves-core-dynlink Draft Initial Version 00:
o This initial version is based on the text regarding the dynamic o This initial version is based on the text regarding the dynamic
linking functionality in I.D.ietf-core-interfaces-05. linking functionality in I.D.ietf-core-interfaces-05.
o The WADL description has been dropped in favour of a thorough o The WADL description has been dropped in favour of a thorough
 End of changes. 59 change blocks. 
207 lines changed or deleted 337 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/