draft-ietf-core-interfaces-09.txt   draft-ietf-core-interfaces-10.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 M. Vial
Expires: September 14, 2017 Schneider-Electric Expires: March 18, 2018 Schneider-Electric
M. Koster M. Koster
SmartThings SmartThings
C. Groves C. Groves
J. Zhu
Huawei Huawei
March 13, 2017 B. Silverajan, Ed.
Tampere University of Technology
September 14, 2017
Reusable Interface Definitions for Constrained RESTful Environments Reusable Interface Definitions for Constrained RESTful Environments
draft-ietf-core-interfaces-09 draft-ietf-core-interfaces-10
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 Parameter, 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
collections. This document further describes how collections relate collections. This document further describes how collections relate
to interfaces. to interfaces.
Many applications require a set of interface descriptions in order Many applications require a set of interface descriptions in order
provide the required functionality. This document defines the provide the required functionality. This document defines the
concept of function sets to specify this set of interfaces and concept of function sets to specify this set of interfaces and
resources. resources.
_Editor's note: The git repository for the draft is found at Editor's notes:
https://github.com/core-wg/interfaces_
_Editor's note: Two open issues are proposals for: Removing the o The git repository for the draft is found at https://github.com/
binding interface in favour of the link list interface. Changing core-wg/interfaces
"rel" type from one attribute to two to indicate src and
destination._
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 September 14, 2017. This Internet-Draft will expire on March 18, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 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 4, line 7 skipping to change at page 4, line 9
This document defines a set of Link Format interface descriptions for This document defines a set of Link Format interface descriptions for
some common design patterns that enable the server side composition some common design patterns that enable the server side composition
and organization, and client side discovery and consumption, of and organization, and client side discovery and consumption, of
machine resources using Web Linking. A client discovering the "if" machine resources using Web Linking. A client discovering the "if"
link attribute will be able to consume resources based on its link attribute will be able to consume resources based on its
knowledge of the expected interface types. In this sense the knowledge of the expected interface types. In this sense the
Interface Type acts in a similar way as a Content-Format, but as a Interface Type acts in a similar way as a Content-Format, but as a
selector for a high level functional abstraction. selector for a high level functional abstraction.
An interface description describes a resource in terms of it's An interface description describes a resource in terms of its
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, and actuators.
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.
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. these interface descriptions utilise collections.
skipping to change at page 8, line 36 skipping to change at page 8, line 42
3.6. Observing Collections 3.6. Observing Collections
Resource Observation via [I-D.ietf-core-dynlink] using CoAP [RFC7252] Resource Observation via [I-D.ietf-core-dynlink] using CoAP [RFC7252]
MAY be supported on items in a collection. A subset of the MAY be supported on items in a collection. A subset of the
conditional observe parameters MAY be specified to apply. In most conditional observe parameters MAY be specified to apply. In most
cases pmin and pmax are useful. Resource observation on a cases pmin and pmax are useful. Resource observation on a
collection's items resource returns the collection representation. collection's items resource returns the collection representation.
Observation Responses, or notifications, SHOULD provide the Observation Responses, or notifications, SHOULD provide the
collection representations in SenML Content-Format. Notifications collection representations in SenML Content-Format. Notifications
MAY include multiple observations of the colection resource, with MAY include multiple observations of the collection resource, with
SenML time stamps indicating the observation times. SenML time stamps indicating the observation times.
3.7. Collection Types 3.7. Collection Types
There are three collection types defined in this document: There are three collection types defined in this document:
+-----------------+---------+--------------------+ +-----------------+---------+--------------------+
| Collection Type | if= | Content-Format | | Collection Type | if= | Content-Format |
+-----------------+---------+--------------------+ +-----------------+---------+--------------------+
| Link List | core.ll | link-format | | Link List | core.ll | link-format |
skipping to change at page 18, line 7 skipping to change at page 18, line 7
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.
8. Changelog 8. Changelog
Changes from -10 to 09:
o Section 1: Amendments to remove discussing properties.
o
o New author and editor added.
Changes from -08 to 09: Changes from -08 to 09:
o Section 3.6: Modified to indicate that the entire collection o Section 3.6: Modified to indicate that the entire collection
resource is returned. resource is returned.
o General: Added editor's note with open issues. o General: Added editor's note with open issues.
Changes from -07 to 08: Changes from -07 to 08:
o Section 3.3: Modified Accepts to Accept header option. o Section 3.3: Modified Accepts to Accept header option.
skipping to change at page 21, line 10 skipping to change at page 21, line 14
o Improved the WADL interface definition. o Improved the WADL interface definition.
o Added a simple profile example. o Added a simple profile example.
9. References 9. References
9.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/
DOI 10.17487/RFC2119, March 1997, RFC2119, March 1997, <https://www.rfc-editor.org/info/
<http://www.rfc-editor.org/info/rfc2119>. rfc2119>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/
DOI 10.17487/RFC5988, October 2010, RFC5988, October 2010, <https://www.rfc-editor.org/info/
<http://www.rfc-editor.org/info/rfc5988>. 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>. <https://www.rfc-editor.org/info/rfc6690>.
9.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-02 (work in progress), February draft-ietf-core-dynlink-03 (work in progress), March 2017.
2017.
[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., Stok, P., and C.
Resource Directory", draft-ietf-core-resource-directory-10 Amsuess, "CoRE Resource Directory", draft-ietf-core-
(work in progress), March 2017. resource-directory-11 (work in progress), July 2017.
[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 Measurement Lists Bormann, "Media Types for Sensor Measurement Lists
(SenML)", draft-ietf-core-senml-05 (work in progress), (SenML)", draft-ietf-core-senml-10 (work in progress),
March 2017. July 2017.
[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]
"Lightweight Machine to Machine Technical Specification", "Lightweight Machine to Machine Technical Specification",
2016, <http://technical.openmobilealliance.org/Technical/ 2016, <http://technical.openmobilealliance.org/Technical/
technical-information/release-program/current-releases/ technical-information/release-program/current-releases/
oma-lightweightm2m-v1-0>. oma-lightweightm2m-v1-0>.
[oneM2MTS0008]
"TS 0008 v1.3.2 CoAP Protocol Binding", 2016,
<http://www.onem2m.org/technical/published-documents>.
[oneM2MTS0023]
"TS 0023 v2.0.0 Home Appliances Information Model and
Mapping", 2016,
<http://www.onem2m.org/technical/published-documents>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66, RFC
RFC 3986, DOI 10.17487/RFC3986, January 2005, 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[RFC6573] Amundsen, M., "The Item and Collection Link Relations", [RFC6573] Amundsen, M., "The Item and Collection Link Relations",
RFC 6573, DOI 10.17487/RFC6573, April 2012, RFC 6573, DOI 10.17487/RFC6573, April 2012,
<http://www.rfc-editor.org/info/rfc6573>. <https://www.rfc-editor.org/info/rfc6573>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing", Protocol (HTTP/1.1): Message Syntax and Routing", RFC
RFC 7230, DOI 10.17487/RFC7230, June 2014, 7230, DOI 10.17487/RFC7230, June 2014, <https://www.rfc-
<http://www.rfc-editor.org/info/rfc7230>. editor.org/info/rfc7230>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252, DOI 10.17487/
DOI 10.17487/RFC7252, June 2014, RFC7252, June 2014, <https://www.rfc-editor.org/info/
<http://www.rfc-editor.org/info/rfc7252>. 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, <https://www.rfc-
<http://www.rfc-editor.org/info/rfc7396>. editor.org/info/rfc7396>.
[oneM2MTS0008]
"TS 0008 v1.3.2 CoAP Protocol Binding", 2016,
<http://www.onem2m.org/technical/published-documents>.
[oneM2MTS0023]
"TS 0023 v2.0.0 Home Appliances Information Model and
Mapping", 2016,
<http://www.onem2m.org/technical/published-documents>.
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 Editor's note: This appendix will be removed. It is only included
for information. 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 consistency 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)
[RFC6690] assumes that different deployments or application domains [RFC6690] assumes that different deployments or application domains
will define the appropriate REST Interface Descriptions along with will define the appropriate REST Interface Descriptions along with
Resource Types to make discovery meaningful. It highlights that Resource Types to make discovery meaningful. It highlights that
collections are often used for these interfaces. collections are often used for these interfaces.
Whilst 3.2/[RFC6690] defines a new Interface Description 'if' Whilst 3.2/[RFC6690] defines a new Interface Description 'if'
skipping to change at page 23, line 31 skipping to change at page 23, line 31
A.2. CoRE Resource Directory (IETF) A.2. CoRE Resource Directory (IETF)
[I-D.ietf-core-resource-directory] uses the concepts of collections, [I-D.ietf-core-resource-directory] uses the concepts of collections,
interfaces and function sets. interfaces and function sets.
If defines a number of interfaces: discovery, registration, If defines a number of interfaces: discovery, registration,
registration update, registration removal, read endpoint links, registration update, registration removal, read endpoint links,
update endpoint links, registration request interface, removal update endpoint links, registration request interface, removal
request interface and lookup interface. However it does not assign request interface and lookup interface. However it does not assign
an inteface description identifier (if=) to these interfaces. an interface description identifier (if=) to these interfaces.
It does define a resource directory function set which specifies It does define a resource directory function set which specifies
relevant content formats and interfaces to be used between a resource relevant content formats and interfaces to be used between a resource
directory and endpoints. However it does not follow the format directory and endpoints. However it does not follow the format
proposed by this document. proposed by this document.
A.3. Open Connectivity Foundation (OCF) A.3. Open Connectivity Foundation (OCF)
The OIC Core Specification [OIC-Core] most closely aligns with the The OIC Core Specification [OIC-Core] most closely aligns with the
work in this specification. It makes use of interface descriptions work in this specification. It makes use of interface descriptions
skipping to change at page 27, line 13 skipping to change at page 27, line 13
Email: matthieu.vial@schneider-electric.com Email: matthieu.vial@schneider-electric.com
Michael Koster Michael Koster
SmartThings SmartThings
665 Clyde Avenue 665 Clyde Avenue
Mountain View 94043 Mountain View 94043
USA USA
Email: michael.koster@smartthings.com Email: michael.koster@smartthings.com
Christian Groves Christian Groves
Huawei
Australia Australia
Email: cngroves.std@gmail.com Email: cngroves.std@gmail.com
Julian Zhu
Huawei
No.127 Jinye Road, Huawei Base, High-Tech Development District
Xi'an, Shaanxi Province
China
Email: jintao.zhu@huawei.com
Bilhanan Silverajan (editor)
Tampere University of Technology
Korkeakoulunkatu 10
Tampere FI-33720
Finland
Email: bilhanan.silverajan@tut.fi
 End of changes. 28 change blocks. 
53 lines changed or deleted 60 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/