draft-ietf-core-interfaces-06.txt   draft-ietf-core-interfaces-07.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: May 1, 2017 Schneider-Electric Expires: June 24, 2017 Schneider-Electric
M. Koster M. Koster
SmartThings SmartThings
C. Groves C. Groves
Huawei Huawei
October 28, 2016 December 21, 2016
Reusable Interface Definitions for Constrained RESTful Environments Reusable Interface Definitions for Constrained RESTful Environments
draft-ietf-core-interfaces-06 draft-ietf-core-interfaces-07
Abstract Abstract
This document defines a set of Constrained RESTful Environments This document defines a set of Constrained RESTful Environments
(CoRE) Link Format Interface Descriptions [RFC6690] applicable for (CoRE) Link Format Interface Descriptions [RFC6690] applicable for
use in constrained environments. These include the: Actuator, use in constrained environments. These include the: Actuator,
Paramter, Read-only parameter, Sensor, Batch, Linked Batch and Link Paramter, Read-only parameter, Sensor, Batch, Linked Batch and Link
List interfaces. List interfaces.
The Batch, Linked Batch and Link List interfaces make use of resource The Batch, Linked Batch and Link List interfaces make use of resource
skipping to change at page 2, line 4 skipping to change at page 2, line 4
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 May 1, 2017. This Internet-Draft will expire on June 24, 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
skipping to change at page 2, line 32 skipping to change at page 2, line 32
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Collections . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Collections . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Introduction to Collections . . . . . . . . . . . . . . . 5 3.1. Introduction to Collections . . . . . . . . . . . . . . . 5
3.2. Use Cases for Collections . . . . . . . . . . . . . . . . 6 3.2. Use Cases for Collections . . . . . . . . . . . . . . . . 6
3.3. Content-Formats for Collections . . . . . . . . . . . . . 6 3.3. Content-Formats for Collections . . . . . . . . . . . . . 6
3.4. Links and Items in Collections . . . . . . . . . . . . . 7 3.4. Links and Items in Collections . . . . . . . . . . . . . 7
3.5. Queries on Collections . . . . . . . . . . . . . . . . . 8 3.5. Queries on Collections . . . . . . . . . . . . . . . . . 8
3.6. Observing Collections . . . . . . . . . . . . . . . . . . 8 3.6. Observing Collections . . . . . . . . . . . . . . . . . . 8
3.7. Collection Types . . . . . . . . . . . . . . . . . . . . 9 3.7. Collection Types . . . . . . . . . . . . . . . . . . . . 8
4. Interface Descriptions . . . . . . . . . . . . . . . . . . . 9 4. Interface Descriptions . . . . . . . . . . . . . . . . . . . 9
4.1. Link List . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1. Link List . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2. Batch . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2. Batch . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.3. Linked Batch . . . . . . . . . . . . . . . . . . . . . . 12 4.3. Linked Batch . . . . . . . . . . . . . . . . . . . . . . 12
4.4. Sensor . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.4. Sensor . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.5. Parameter . . . . . . . . . . . . . . . . . . . . . . . . 14 4.5. Parameter . . . . . . . . . . . . . . . . . . . . . . . . 14
4.6. Read-only Parameter . . . . . . . . . . . . . . . . . . . 14 4.6. Read-only Parameter . . . . . . . . . . . . . . . . . . . 14
4.7. Actuator . . . . . . . . . . . . . . . . . . . . . . . . 14 4.7. Actuator . . . . . . . . . . . . . . . . . . . . . . . . 14
5. Function Sets and Profiles . . . . . . . . . . . . . . . . . 15 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15
5.1. Defining a Function Set . . . . . . . . . . . . . . . . . 16 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
5.1.1. Path template . . . . . . . . . . . . . . . . . . . . 16 6.1. Link List . . . . . . . . . . . . . . . . . . . . . . . . 15
5.1.2. Resource Type . . . . . . . . . . . . . . . . . . . . 16 6.2. Batch . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.1.3. Interface Description . . . . . . . . . . . . . . . . 17 6.3. Linked Batch . . . . . . . . . . . . . . . . . . . . . . 16
5.1.4. Data type . . . . . . . . . . . . . . . . . . . . . . 17 6.4. Sensor . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 17 6.5. Parameter . . . . . . . . . . . . . . . . . . . . . . . . 16
5.3. Versioning . . . . . . . . . . . . . . . . . . . . . . . 17 6.6. Read-only parameter . . . . . . . . . . . . . . . . . . . 17
6. Security Considerations . . . . . . . . . . . . . . . . . . . 18 6.7. Actuator . . . . . . . . . . . . . . . . . . . . . . . . 17
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17
7.1. Link List . . . . . . . . . . . . . . . . . . . . . . . . 18 8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 18
7.2. Batch . . . . . . . . . . . . . . . . . . . . . . . . . . 18 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 20
7.3. Linked Batch . . . . . . . . . . . . . . . . . . . . . . 18 9.1. Normative References . . . . . . . . . . . . . . . . . . 20
7.4. Sensor . . . . . . . . . . . . . . . . . . . . . . . . . 19 9.2. Informative References . . . . . . . . . . . . . . . . . 21
7.5. Parameter . . . . . . . . . . . . . . . . . . . . . . . . 19 Appendix A. Current Usage of Interfaces and Function Sets . . . 22
7.6. Read-only parameter . . . . . . . . . . . . . . . . . . . 19
7.7. Actuator . . . . . . . . . . . . . . . . . . . . . . . . 19
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 20
9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 20
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 22
10.1. Normative References . . . . . . . . . . . . . . . . . . 23
10.2. Informative References . . . . . . . . . . . . . . . . . 23
Appendix A. Current Usage of Interfaces and Function Sets . . . 24
A.1. Constrained RESTful Environments (CoRE) Link Format A.1. Constrained RESTful Environments (CoRE) Link Format
(IETF) . . . . . . . . . . . . . . . . . . . . . . . . . 25 (IETF) . . . . . . . . . . . . . . . . . . . . . . . . . 22
A.2. CoRE Resource Directory (IETF) . . . . . . . . . . . . . 25 A.2. CoRE Resource Directory (IETF) . . . . . . . . . . . . . 23
A.3. Open Connectivity Foundation (OCF) . . . . . . . . . . . 25 A.3. Open Connectivity Foundation (OCF) . . . . . . . . . . . 23
A.4. oneM2M . . . . . . . . . . . . . . . . . . . . . . . . . 26 A.4. oneM2M . . . . . . . . . . . . . . . . . . . . . . . . . 24
A.5. OMA LWM2M . . . . . . . . . . . . . . . . . . . . . . . . 26 A.5. OMA LWM2M . . . . . . . . . . . . . . . . . . . . . . . . 24
Appendix B. Profile example . . . . . . . . . . . . . . . . . . 27 Appendix B. Resource Profile example . . . . . . . . . . . . . . 25
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26
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. SenML for doing Web Linking [RFC5988] in constrained environments. SenML
[I-D.ietf-core-senml] is a simple data model and representation [I-D.ietf-core-senml] is a simple data model and representation
format for composite and complex structured resources. CoRE Link- format for composite and complex structured resources. CoRE Link-
skipping to change at page 4, line 18 skipping to change at page 4, line 11
An interface description describes a resource in terms of it's An interface description describes a resource in terms of it's
associated content formats, data types, URI templates, REST methods, associated content formats, data types, URI templates, REST methods,
parameters, and responses. Basic interface descriptions are defined parameters, and responses. Basic interface descriptions are defined
for sensors, actuators, and properties. for sensors, actuators, and properties.
A set of collection types is defined for organizing resources for A set of collection types is defined for organizing resources for
discovery, and for various forms of bulk interaction with resource discovery, and for various forms of bulk interaction with resource
sets using typed embedding links. sets using typed embedding links.
Interface descriptions may be used in the composition of Function
Sets and Profiles. Function Sets and Profiles are described and an
example is given of a sensor and actuator device profile using
Function Sets composed from the interface descriptions described in
this document.
This document first defines the concept of collection interface This document first defines the concept of collection interface
descriptions. It then defines a number of generic interface descriptions. It then defines a number of generic interface
descriptions that may be used in contrained environments. Several of descriptions that may be used in contrained environments. Several of
these interface descriptions utilise collections. The interface these interface descriptions utilise collections.
descriptions are then used by the function sets.
Whilst this document assumes the use of CoAP [RFC7252], the REST Whilst this document assumes the use of CoAP [RFC7252], the REST
interfaces described can also be realized using HTTP [RFC7230]. interfaces described can also be realized using HTTP [RFC7230].
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 document are to be interpreted as described in
[RFC2119]. [RFC2119].
This document requires readers to be familiar with all the terms and This document requires readers to be familiar with all the terms and
concepts that are discussed in [RFC5988] and [RFC6690]. This concepts that are discussed in [RFC5988] and [RFC6690]. This
document makes use of the following additional terminology: document makes use of the following additional terminology:
Device: An IP smart object running a web server that hosts a group
of Function Set instances from a profile.
Function Set: A group of well-known REST resources that provides a
particular service.
Gradual Reveal: A REST design where resources are discovered Gradual Reveal: A REST design where resources are discovered
progressively using Web Linking. progressively using Web Linking.
Interface Description: The Interface Description describes the Interface Description: The Interface Description describes the
generic REST interface to interact with a resource or a set of generic REST interface to interact with a resource or a set of
resources. Its use is described via the Interface Description resources. Its use is described via the Interface Description
'if' attribute which is an opaque string used to provide a name or 'if' attribute which is an opaque string used to provide a name or
URI indicating a specific interface definition used to interact URI indicating a specific interface definition used to interact
with the target resource. One can think of this as describing with the target resource. One can think of this as describing
verbs usable on a resource. verbs usable on a resource.
Profile: A group of well-known Function Sets defined by a
specification.
Resource Discovery: The process allowing a web client to identify Resource Discovery: The process allowing a web client to identify
resources being hosted on a web server. resources being hosted on a web server.
Service Discovery: The process making it possible for a web client Service Discovery: The process making it possible for a web client
to automatically detect devices and Function Sets offered by these to automatically detect devices and Function Sets offered by these
devices on a CoRE network. devices on a CoRE network.
3. Collections 3. Collections
3.1. Introduction to Collections 3.1. Introduction to Collections
skipping to change at page 10, line 37 skipping to change at page 10, line 37
| | | | | | | | | |
| Actuator | core.a | GET, PUT, POST | link-format, | | Actuator | core.a | GET, PUT, POST | link-format, |
| | | | | | | | | |
| | | | text/plain | | | | | text/plain |
+--------------+---------+-----------------+--------------------+ +--------------+---------+-----------------+--------------------+
Table 2: Interface Description Summary Table 2: Interface Description Summary
The following is an example of links in the CoRE Link Format using The following is an example of links in the CoRE Link Format using
these interface descriptions. The resource hierarchy is based on a these interface descriptions. The resource hierarchy is based on a
simple profile defined in Appendix B. These links are used in the simple resource profile defined in Appendix B. These links are used
subsequent examples below. in the subsequent examples below.
Req: GET /.well-known/core Req: GET /.well-known/core
Res: 2.05 Content (application/link-format) Res: 2.05 Content (application/link-format)
</s/>;rt="simple.sen";if="core.b", </s/>;rt="simple.sen";if="core.b",
</s/lt>;rt="simple.sen.lt";if="core.s", </s/light>;rt="simple.sen.lt";if="core.s",
</s/tmp>;rt="simple.sen.tmp";if="core.s";obs, </s/temp>;rt="simple.sen.tmp";if="core.s";obs,
</s/hum>;rt="simple.sen.hum";if="core.s", </s/humidity>;rt="simple.sen.hum";if="core.s",
</a/>;rt="simple.act";if="core.b", </a/>;rt="simple.act";if="core.b",
</a/1/led>;rt="simple.act.led";if="core.a", </a/1/led>;rt="simple.act.led";if="core.a",
</a/2/led>;rt="simple.act.led";if="core.a", </a/2/led>;rt="simple.act.led";if="core.a",
</d/>;rt="simple.dev";if="core.ll", </d/>;rt="simple.dev";if="core.ll",
</l/>;if="core.lb", </l/>;if="core.lb",
Figure 1: Binding Interface Example Figure 1: Binding Interface Example
4.1. Link List 4.1. Link List
skipping to change at page 11, line 49 skipping to change at page 11, line 49
resources at the same time. The Batch interface description supports resources at the same time. The Batch interface description supports
the same methods as its sub-resources, and can be used to read (GET), the same methods as its sub-resources, and can be used to read (GET),
update (PUT) or apply (POST) the values of those sub-resource with a update (PUT) or apply (POST) the values of those sub-resource with a
single resource representation. The sub-resources of a Batch MAY be single resource representation. The sub-resources of a Batch MAY be
heterogeneous, a method used on the Batch only applies to sub- heterogeneous, a method used on the Batch only applies to sub-
resources that support it. For example Sensor interfaces do not resources that support it. For example Sensor interfaces do not
support PUT, and thus a PUT request to a Sensor member of that Batch support PUT, and thus a PUT request to a Sensor member of that Batch
would be ignored. A batch requires the use of SenML Media types in would be ignored. A batch requires the use of SenML Media types in
order to support multiple sub-resources. order to support multiple sub-resources.
In addition, The Batch interface is an extension of the Link List In addition, the Batch interface is an extension of the Link List
interface and in consequence MUST support the same methods. interface and in consequence MUST support the same methods. For
example: a GET with an Accept:application/link-format on a resource
_Editor's note: hould probably explain that this means doing a GET utilizing the batch interface will return the sub-resource links.
with an Accept:application/link-format will return the sub-resource
links_
The following example interacts with a Batch /s/ with Sensor sub- The following example interacts with a Batch /s/ with Sensor sub-
resources /s/light, /s/temp and /s/humidity. resources /s/light, /s/temp and /s/humidity.
Req: GET /s/ Req: GET /s/
Res: 2.05 Content (application/senml+json) Res: 2.05 Content (application/senml+json)
{"e":[ {"e":[
{ "n": "light", "v": 123, "u": "lx" }, { "n": "light", "v": 123, "u": "lx" },
{ "n": "temp", "v": 27.2, "u": "degC" }, { "n": "temp", "v": 27.2, "u": "degC" },
{ "n": "humidity", "v": 80, "u": "%RH" }], { "n": "humidity", "v": 80, "u": "%RH" }],
skipping to change at page 15, line 28 skipping to change at page 15, line 28
1 1
Res: 2.04 Changed Res: 2.04 Changed
Req: POST /a/1/led (text/plain) Req: POST /a/1/led (text/plain)
Res: 2.04 Changed Res: 2.04 Changed
Req: GET /a/1/led Req: GET /a/1/led
Res: 2.05 Content (text/plain) Res: 2.05 Content (text/plain)
0 0
5. Function Sets and Profiles 5. Security Considerations
This section defines how a set of REST resources can be created
called a function set. A Function Set is similar to a function block
in the sense that it consists of input, output and parameter
resources and contains internal logic. A Function Set can have a
subset of mandatory inputs, outputs and parameters to provide minimum
interoperability. It can also be extended with manufacturer/user-
specific resources. A device is composed of one or more Function Set
instances.
An example of function sets can be found from the CoRE Resource
Directory specification that defines REST interfaces for
registration, group and lookup [I-D.ietf-core-resource-directory].
The OMA Lightweight M2M standard [OMA-TS-LWM2M] also defines a
function set structure called an Objects that use integer path,
instance and resource URI segments. OMA Objects can be defined and
then registered with an OMA maintained registry [OMA-TS-LWM2M]. This
section is simply meant as a guideline for the definition of other
such REST interfaces, either custom or part of other specifications.
5.1. Defining a Function Set
In a Function Set, types of resources are defined. Each type
includes a human readable name, a path template, a Resource Type for
discovery, the Interface Definition and the data type and allowed
values. A Function Set definition may also include a field
indicating if a sub-resource is mandatory or optional.
5.1.1. Path template
A Function Set is a container resource under which its sub-resources
are organized. The profile defines the path to each resource of a
Function Set in a path template. The template can contain either
relative paths or absolute paths depending on the profile needs. An
absolute Function Set should be located at its recommended root path
on a web server, however it can be located under an alternative path
if necessary (for example multi-purpose devices, gateways etc.). A
relative Function Set can be instantiated as many times as needed on
a web server with an arbitrary root path. However some Function Sets
(e.g. device description) only make sense as singletons.
The path template includes a possible index {#} parameter, and
possible fixed path segments. The index {#} allows for multiple
instances of this type of resource, and can be any string. The root
path and the indexes are the only variable elements in a path
template. All other path segments should be fixed.
5.1.2. Resource Type
Each root resource of a Function Set is assigned a Resource Type
parameter, therefore making it possible to discover it. Each sub-
resource of a Function Set is also assigned a Resource Type
parameter. This Resource Type is used for resource discovery and is
usually necessary to discover optional resources supported on a
specific device. The Resource Type of a Function Set may also be
used for service discovery and can be exported to DNS-SD [RFC6763]
for example.
The Resource Type parameter defines the value that should be included
in the rt= field of the CoRE Link Format when describing a link to
this resource. The value SHOULD be in the form "namespace.type" for
root resources and "namespace.type.subtype" for sub-resources. This
naming convention facilitates resource type filtering with the
/.well-known/core resource. However a profile could allow mixing in
foreign namespace references within a Function Set to import external
references from other object models (e.g. SenML and UCUM).
5.1.3. Interface Description
The Interface Description parameter defines the REST interface for
that type of resource. Several base interfaces are defined in
Section 4 of this document. For a given profile, the Interface
Description may be inferred from the Resource Type. In that case the
Interface Description MAY be elided from link descriptions of
resource types defined in the profile, but should be included for
custom extensions to the profile.
The root resource of a Function Set should provide a list of links to
its sub-resources in order to offer gradual reveal of resources. The
CoRE Link List interface defined in Section 7.1 offers this
functionality so a root resource should support this interface or a
derived interface like CoRE Batch (See Section 7.2).
5.1.4. Data type
The Data Type field defines the type of value (and possible range)
that is returned in response to a GET for that resource or accepted
with a PUT. The interfaces defined in Section 4 make use of plain
text and SenML Media types for the actual format of this data. A
profile may restrict the list of supported content formats for the
CoRE interfaces or define new interfaces with new content types.
5.2. Discovery
A device conforming to a profile SHOULD make its resources
discoverable by providing links to the resources on the path /.well-
known/core as defined in [RFC6690]. All resources hosted on a device
SHOULD be discoverable either with a direct link in /.well-known/core
or by following successive links starting from /.well-known/core.
The root path of a Function Set instance SHOULD be directly
referenced in /.well-known/core in order to offer discovery at the
first discovery stage. A device with more than 10 individual
resources SHOULD only expose Function Set instances in /.well-known/
core to limit the size of this resource.
In addition, a device MAY register its resources to a Resource
Directory using the registration interface defined in
[I-D.ietf-core-resource-directory] if such a directory is available.
5.3. Versioning
A profile should track Function Set changes to avoid incompatibility
issues. Evolutions in a Function Set SHOULD be backward compatible.
6. Security Considerations
An implementation of a client needs to be prepared to deal with An implementation of a client needs to be prepared to deal with
responses to a request that differ from what is specified in this responses to a request that differ from what is specified in this
document. A server implementing what the client thinks is a resource document. A server implementing what the client thinks is a resource
with one of these interface descriptions could return malformed with one of these interface descriptions could return malformed
representations and response codes either by accident or maliciously. representations and response codes either by accident or maliciously.
A server sending maliciously malformed responses could attempt to A server sending maliciously malformed responses could attempt to
take advantage of a poorly implemented client for example to crash take advantage of a poorly implemented client for example to crash
the node or perform denial of service. the node or perform denial of service.
7. IANA Considerations 6. IANA Considerations
This document registers the following CoRE Interface Description This document registers the following CoRE Interface Description
(if=) Link Target Attribute Values. (if=) Link Target Attribute Values.
7.1. Link List 6.1. Link List
Attribute Value: core.ll Attribute Value: core.ll
Description: The Link List interface is used to retrieve a list of Description: The Link List interface is used to retrieve a list of
resources on a web server. resources on a web server.
Reference: This document. Note to RFC Editor - please insert the Reference: This document. Note to RFC Editor - please insert the
appropriate RFC reference. appropriate RFC reference.
Notes: None Notes: None
7.2. Batch 6.2. Batch
Attribute Value: core.b Attribute Value: core.b
Description: The Batch interface is used to manipulate a collection Description: The Batch interface is used to manipulate a collection
of sub-resources at the same time. of sub-resources at the same time.
Reference: This document. Note to RFC Editor - please insert the Reference: This document. Note to RFC Editor - please insert the
appropriate RFC reference. appropriate RFC reference.
Notes: None Notes: None
7.3. Linked Batch 6.3. Linked Batch
Attribute Value: core.lb Attribute Value: core.lb
Description: The Linked Batch interface is an extension of the Batch Description: The Linked Batch interface is an extension of the Batch
interface. Contrary to the basic Batch which is a collection interface. Contrary to the basic Batch which is a collection
statically defined by the web server, a Linked Batch is statically defined by the web server, a Linked Batch is
dynamically controlled by a web client. dynamically controlled by a web client.
Reference: This document. Note to RFC Editor - please insert the Reference: This document. Note to RFC Editor - please insert the
appropriate RFC reference. appropriate RFC reference.
Notes: None Notes: None
7.4. Sensor 6.4. Sensor
Attribute Value: core.s Attribute Value: core.s
Description: The Sensor interface allows the value of a sensor Description: The Sensor interface allows the value of a sensor
resource to be read. resource to be read.
Reference: This document. Note to RFC Editor - please insert the Reference: This document. Note to RFC Editor - please insert the
appropriate RFC reference. appropriate RFC reference.
Notes: None Notes: None
7.5. Parameter 6.5. Parameter
Attribute Value: core.p Attribute Value: core.p
Description: The Parameter interface allows configurable parameters Description: The Parameter interface allows configurable parameters
and other information to be modeled as a resource. The value of and other information to be modeled as a resource. The value of
the parameter can be read or update. the parameter can be read or update.
Reference: This document. Note to RFC Editor - please insert the Reference: This document. Note to RFC Editor - please insert the
appropriate RFC reference. appropriate RFC reference.
Notes: None Notes: None
7.6. Read-only parameter 6.6. Read-only parameter
Attribute Value: core.rp Attribute Value: core.rp
Description: The Read-only Parameter interface allows configuration Description: The Read-only Parameter interface allows configuration
parameters to be read but not updated. parameters to be read but not updated.
Reference: This document. Note to RFC Editor - please insert the Reference: This document. Note to RFC Editor - please insert the
appropriate RFC reference. appropriate RFC reference.
Notes: None Notes: None
7.7. Actuator 6.7. Actuator
Attribute Value: core.a Attribute Value: core.a
Description: The Actuator interface is used by resources that model Description: The Actuator interface is used by resources that model
different kinds of actuators (changing its value has an effect on different kinds of actuators (changing its value has an effect on
its environment). Examples of actuators include for example LEDs, its environment). Examples of actuators include for example LEDs,
relays, motor controllers and light dimmers. The current value of relays, motor controllers and light dimmers. The current value of
the actuator can be read or the actuator value can be updated. In the actuator can be read or the actuator value can be updated. In
addition, this interface allows the use of POST to change the addition, this interface allows the use of POST to change the
state of an actuator, for example to toggle between its possible state of an actuator, for example to toggle between its possible
values. values.
Reference: This document. Note to RFC Editor - please insert the Reference: This document. Note to RFC Editor - please insert the
appropriate RFC reference. appropriate RFC reference.
Notes: None Notes: None
8. 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 descriptions have been discussed, and to requirements for interface descriptions have been discussed, and to
Szymon Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann Szymon Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann
who have provided useful discussion and input to the concepts in this who have provided useful discussion and input to the concepts in this
document. document.
9. Changelog 8. Changelog
Changes from -06 to 07:
o Corrected Figure 1 sub-resource names e.g. tmp to temp and hum to
humidity.
o Addressed the editor's note in Section 4.2.
o Removed section on function sets and profiles as agreed to at the
IETF#97.
Changes from -05 to -06: Changes from -05 to -06:
o Updated the abstract. o Updated the abstract.
o Section 1: Updated introduction. o Section 1: Updated introduction.
o Section 2: Alphabetised the order o Section 2: Alphabetised the order
o Section 2: Removed the collections definition in favour of the o Section 2: Removed the collections definition in favour of the
skipping to change at page 22, line 47 skipping to change at page 20, line 34
o Defined a Function Set and its guidelines. o Defined a Function Set and its guidelines.
o Added the Link List interface. o Added the Link List interface.
o Added the Linked Batch interface. o Added the Linked Batch interface.
o Improved the WADL interface definition. o Improved the WADL interface definition.
o Added a simple profile example. o Added a simple profile example.
10. References 9. References
10.1. Normative References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, [RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010, DOI 10.17487/RFC5988, October 2010,
<http://www.rfc-editor.org/info/rfc5988>. <http://www.rfc-editor.org/info/rfc5988>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<http://www.rfc-editor.org/info/rfc6690>. <http://www.rfc-editor.org/info/rfc6690>.
10.2. Informative References 9.2. Informative References
[I-D.ietf-core-dynlink] [I-D.ietf-core-dynlink]
Shelby, Z., Vial, M., Koster, M., and C. Groves, "Dynamic Shelby, Z., Vial, M., Koster, M., and C. Groves, "Dynamic
Resource Linking for Constrained RESTful Environments", Resource Linking for Constrained RESTful Environments",
draft-ietf-core-dynlink-00 (work in progress), October draft-ietf-core-dynlink-01 (work in progress), October
2016. 2016.
[I-D.ietf-core-resource-directory] [I-D.ietf-core-resource-directory]
Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE
Resource Directory", draft-ietf-core-resource-directory-08 Resource Directory", draft-ietf-core-resource-directory-09
(work in progress), July 2016. (work in progress), October 2016.
[I-D.ietf-core-senml] [I-D.ietf-core-senml]
Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
Bormann, "Media Types for Sensor Markup Language (SenML)", Bormann, "Media Types for Sensor Measurement Lists
draft-ietf-core-senml-03 (work in progress), October 2016. (SenML)", draft-ietf-core-senml-04 (work in progress),
October 2016.
[OIC-Core] [OIC-Core]
"OIC Resource Type Specification v1.1.0", 2016, "OIC Resource Type Specification v1.1.0", 2016,
<https://openconnectivity.org/resources/specifications>. <https://openconnectivity.org/resources/specifications>.
[OIC-SmartHome] [OIC-SmartHome]
"OIC Smart Home Device Specification v1.1.0", 2016, "OIC Smart Home Device Specification v1.1.0", 2016,
<https://openconnectivity.org/resources/specifications>. <https://openconnectivity.org/resources/specifications>.
[OMA-TS-LWM2M] [OMA-TS-LWM2M]
skipping to change at page 24, line 43 skipping to change at page 22, line 29
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>. <http://www.rfc-editor.org/info/rfc7252>.
[RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396,
DOI 10.17487/RFC7396, October 2014, DOI 10.17487/RFC7396, October 2014,
<http://www.rfc-editor.org/info/rfc7396>. <http://www.rfc-editor.org/info/rfc7396>.
Appendix A. Current Usage of Interfaces and Function Sets Appendix A. Current Usage of Interfaces and Function Sets
Editor's note: This appendix will be removed. It is only included
for information.
This appendix analyses the current landscape with regards the This appendix analyses the current landscape with regards the
definition and use of collections, interfaces and function sets/ definition and use of collections, interfaces and function sets/
profiles. This should be considered when considering the scope of profiles. This should be considered when considering the scope of
this document. this document.
In summary it can be seen that there is a lack of consistancy of the In summary it can be seen that there is a lack of consistancy of the
definition and usage of interface description and function sets. definition and usage of interface description and function sets.
A.1. Constrained RESTful Environments (CoRE) Link Format (IETF) A.1. Constrained RESTful Environments (CoRE) Link Format (IETF)
skipping to change at page 27, line 15 skipping to change at page 25, line 5
It does not identify the interfaces through an Interface Description It does not identify the interfaces through an Interface Description
(if=) attribute. (if=) attribute.
It does not use the term function set. Informally the specification It does not use the term function set. Informally the specification
could be considered as a function set. could be considered as a function set.
Note: It refers to draft-ietf-core-interfaces-00. It also makes use Note: It refers to draft-ietf-core-interfaces-00. It also makes use
of the binding/observation attributes from draft-ietf-dynlink-00 but of the binding/observation attributes from draft-ietf-dynlink-00 but
does not refer to that document. does not refer to that document.
Appendix B. Profile example Appendix B. Resource Profile example
The following is a short definition of simple profile. This The following is a short definition of simple device resource
simplistic profile is for use in the examples of this document. profile. This simplistic profile is for use in the examples of this
document.
+--------------------+-----------+------------+---------+ +--------------------+-----------+------------+---------+
| Function Set | Root Path | RT | IF | | Functions | Root Path | RT | IF |
+--------------------+-----------+------------+---------+ +--------------------+-----------+------------+---------+
| Device Description | /d | simple.dev | core.ll | | Device Description | /d | simple.dev | core.ll |
| | | | | | | | | |
| Sensors | /s | simple.sen | core.b | | Sensors | /s | simple.sen | core.b |
| | | | | | | | | |
| Actuators | /a | simple.act | core.b | | Actuators | /a | simple.act | core.b |
+--------------------+-----------+------------+---------+ +--------------------+-----------+------------+---------+
Table 3: List of Function Sets Table 3: Functional list of resources
+-------+----------+----------------+---------+------------+ +-------+----------+----------------+---------+------------+
| Type | Path | RT | IF | Data Type | | Type | Path | RT | IF | Data Type |
+-------+----------+----------------+---------+------------+ +-------+----------+----------------+---------+------------+
| Name | /d/name | simple.dev.n | core.p | xsd:string | | Name | /d/name | simple.dev.n | core.p | xsd:string |
| | | | | | | | | | | |
| Model | /d/model | simple.dev.mdl | core.rp | xsd:string | | Model | /d/model | simple.dev.mdl | core.rp | xsd:string |
+-------+----------+----------------+---------+------------+ +-------+----------+----------------+---------+------------+
Table 4: Device Description Function Set Table 4: Device Description Resources
+-------------+-------------+----------------+--------+-------------+ +-------------+-------------+----------------+--------+-------------+
| Type | Path | RT | IF | Data Type | | Type | Path | RT | IF | Data Type |
+-------------+-------------+----------------+--------+-------------+ +-------------+-------------+----------------+--------+-------------+
| Light | /s/light | simple.sen.lt | core.s | xsd:decimal | | Light | /s/light | simple.sen.lt | core.s | xsd:decimal |
| | | | | | | | | | | |
| | | | | (lux) | | | | | | (lux) |
| | | | | | | | | | | |
| Humidity | /s/humidity | simple.sen.hum | core.s | xsd:decimal | | Humidity | /s/humidity | simple.sen.hum | core.s | xsd:decimal |
| | | | | | | | | | | |
| | | | | (%RH) | | | | | | (%RH) |
| | | | | | | | | | | |
| Temperature | /s/temp | simple.sen.tmp | core.s | xsd:decimal | | Temperature | /s/temp | simple.sen.tmp | core.s | xsd:decimal |
| | | | | | | | | | | |
| | | | | (degC) | | | | | | (degC) |
+-------------+-------------+----------------+--------+-------------+ +-------------+-------------+----------------+--------+-------------+
Table 5: Sensors Function Set Table 5: Sensor Resources
+------+------------+----------------+--------+-------------+ +------+------------+----------------+--------+-------------+
| Type | Path | RT | IF | Data Type | | Type | Path | RT | IF | Data Type |
+------+------------+----------------+--------+-------------+ +------+------------+----------------+--------+-------------+
| LED | /a/{#}/led | simple.act.led | core.a | xsd:boolean | | LED | /a/{#}/led | simple.act.led | core.a | xsd:boolean |
+------+------------+----------------+--------+-------------+ +------+------------+----------------+--------+-------------+
Table 6: Actuators Function Set Table 6: Actuator Resources
Authors' Addresses Authors' Addresses
Zach Shelby Zach Shelby
ARM ARM
150 Rose Orchard 150 Rose Orchard
San Jose 95134 San Jose 95134
FINLAND FINLAND
Phone: +1-408-203-9434 Phone: +1-408-203-9434
 End of changes. 39 change blocks. 
208 lines changed or deleted 80 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/