draft-ietf-core-interfaces-12.txt   draft-ietf-core-interfaces-13.txt 
CoRE Working Group Z. Shelby CoRE Working Group Z. Shelby
Internet-Draft ARM Internet-Draft ARM
Intended status: Informational M. Koster Intended status: Informational M. Koster
Expires: December 29, 2018 SmartThings Expires: April 25, 2019 SmartThings
C. Groves C. Groves
J. Zhu J. Zhu
Huawei Huawei
B. Silverajan, Ed. B. Silverajan, Ed.
Tampere University of Technology Tampere University of Technology
June 27, 2018 October 22, 2018
Reusable Interface Definitions for Constrained RESTful Environments Reusable Interface Definitions for Constrained RESTful Environments
draft-ietf-core-interfaces-12 draft-ietf-core-interfaces-13
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,
Parameter, 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
skipping to change at page 2, line 10 skipping to change at page 2, line 10
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 https://datatracker.ietf.org/drafts/current/. Drafts is at https://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 December 29, 2018. This Internet-Draft will expire on April 25, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 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
(https://trustee.ietf.org/license-info) in effect on the date of (https://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 3, line 5 skipping to change at page 3, line 5
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. Security Considerations . . . . . . . . . . . . . . . . . . . 15 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
6.1. Link List . . . . . . . . . . . . . . . . . . . . . . . . 15 6.1. Link List . . . . . . . . . . . . . . . . . . . . . . . . 15
6.2. Batch . . . . . . . . . . . . . . . . . . . . . . . . . . 16 6.2. Batch . . . . . . . . . . . . . . . . . . . . . . . . . . 16
6.3. Linked Batch . . . . . . . . . . . . . . . . . . . . . . 16 6.3. Linked Batch . . . . . . . . . . . . . . . . . . . . . . 16
6.4. Sensor . . . . . . . . . . . . . . . . . . . . . . . . . 16 6.4. Sensor . . . . . . . . . . . . . . . . . . . . . . . . . 16
6.5. Parameter . . . . . . . . . . . . . . . . . . . . . . . . 16 6.5. Parameter . . . . . . . . . . . . . . . . . . . . . . . . 17
6.6. Read-only parameter . . . . . . . . . . . . . . . . . . . 17 6.6. Read-only parameter . . . . . . . . . . . . . . . . . . . 17
6.7. Actuator . . . . . . . . . . . . . . . . . . . . . . . . 17 6.7. Actuator . . . . . . . . . . . . . . . . . . . . . . . . 17
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17
8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 18 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 18
9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 18 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 18
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 22
10.1. Normative References . . . . . . . . . . . . . . . . . . 21 10.1. Normative References . . . . . . . . . . . . . . . . . . 22
10.2. Informative References . . . . . . . . . . . . . . . . . 22 10.2. Informative References . . . . . . . . . . . . . . . . . 22
Appendix A. Current Usage of Interfaces . . . . . . . . . . . . 23 Appendix A. Current Usage of Interfaces . . . . . . . . . . . . 23
A.1. Constrained RESTful Environments (CoRE) Link Format A.1. Constrained RESTful Environments (CoRE) Link Format
(IETF) . . . . . . . . . . . . . . . . . . . . . . . . . 23 (IETF) . . . . . . . . . . . . . . . . . . . . . . . . . 23
A.2. Open Connectivity Foundation (OCF) . . . . . . . . . . . 23 A.2. Open Connectivity Foundation (OCF) . . . . . . . . . . . 24
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24
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 [RFC8288] in constrained environments. SenML for doing Web Linking [RFC8288] in constrained environments. SenML
[I-D.ietf-core-senml] is a simple data model and representation [RFC8428] is a simple data model and representation format for
format for composite and complex structured resources. CoRE Link- composite and complex structured resources. CoRE Link-Format and
Format and SenML can be used by CoAP [RFC7252] or HTTP servers. SenML can be used by CoAP [RFC7252] or HTTP servers.
The discovery of resources offered by a constrained server is very The discovery of resources offered by a constrained server is very
important in machine-to-machine applications where there are no important in machine-to-machine applications where there are no
humans in the loop. Machine application clients must be able to humans in the loop. Machine application clients must be able to
adapt to different resource organizations without advance knowledge adapt to different resource organizations without advance knowledge
of the specific data structures hosted by each connected thing. The of the specific data structures hosted by each connected thing. The
use of Web Linking for the description and discovery of resources use of Web Linking for the description and discovery of resources
hosted by constrained origin servers is specified by CoRE Link Format hosted by constrained origin servers is specified by CoRE Link Format
[RFC6690]. CoRE Link Format additionally defines a link attribute [RFC6690]. CoRE Link Format additionally defines a link attribute
for interface description ("if") that can be used to describe the for interface description ("if") that can be used to describe the
skipping to change at page 11, line 24 skipping to change at page 11, line 24
Note: The use of an Accept option with application/link-format is Note: The use of an Accept option with application/link-format is
recommended even though it is not strictly needed for the Link List recommended even though it is not strictly needed for the Link List
interface because this interface is extended by the batch and linked interface because this interface is extended by the batch and linked
batch interfaces where different content-formats are possible. batch interfaces where different content-formats are possible.
The request returns a list of URI references with absolute paths to The request returns a list of URI references with absolute paths to
the resources as defined in CoRE Link Format. This interface is the resources as defined in CoRE Link Format. This interface is
typically used with a parent resource to enumerate sub-resources but typically used with a parent resource to enumerate sub-resources but
may be used to reference any resource on an origin server. may be used to reference any resource on an origin server.
The following example interacts with a Link List /d containing The following example interacts with a Link List /d/ containing
Parameter sub-resources /d/name, /d/model. Parameter sub-resources /d/name, /d/model.
Req: GET /d/ (Accept:application/link-format) Req: GET /d/ (Accept:application/link-format)
Res: 2.05 Content (application/link-format) Res: 2.05 Content (application/link-format)
</d/name>;rt="simple.dev.n";if="core.p", </d/name>;rt="simple.dev.n";if="core.p",
</d/model>;rt="simple.dev.mdl";if="core.rp" </d/model>;rt="simple.dev.mdl";if="core.rp"
4.2. Batch 4.2. Batch
The Batch interface is used to manipulate a collection of sub- The Batch interface is used to manipulate a collection of sub-
skipping to change at page 12, line 8 skipping to change at page 12, line 8
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.
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)
[ [
{ "bn": "example.com/s/" },
{ "n": "light", "v": 123, "u": "lx" }, { "n": "light", "v": 123, "u": "lx" },
{ "n": "temp", "v": 27.2, "u": "Cel" }, { "n": "temp", "v": 27.2, "u": "Cel" },
{ "n": "humidity", "v": 80, "u": "%RH" } { "n": "humidity", "v": 80, "u": "%RH" }
] ]
4.3. Linked Batch 4.3. Linked Batch
The Linked Batch interface is an extension of the Batch interface. The Linked Batch interface is an extension of the Batch interface.
Contrary to the basic Batch which is a collection statically defined Contrary to the basic Batch which is a collection statically defined
by the origin server, a Linked Batch is dynamically controlled by a by the origin server, a Linked Batch is dynamically controlled by a
skipping to change at page 13, line 12 skipping to change at page 13, line 12
The following example interacts with a Linked Batch /l/ and creates a The following example interacts with a Linked Batch /l/ and creates a
collection containing /s/light, /s/temp and /s/humidity in 2 steps. collection containing /s/light, /s/temp and /s/humidity in 2 steps.
Req: POST /l/ (Content-Format: application/link-format) Req: POST /l/ (Content-Format: application/link-format)
</s/light>,</s/temp> </s/light>,</s/temp>
Res: 2.04 Changed Res: 2.04 Changed
Req: GET /l/ Req: GET /l/
Res: 2.05 Content (application/senml+json) Res: 2.05 Content (application/senml+json)
[ [
{ "bn": "example.com/" },
{ "n": "/s/light", "v": 123, "u": "lx" }, { "n": "/s/light", "v": 123, "u": "lx" },
{ "n": "/s/temp", "v": 27.2, "u": "Cel" } { "n": "/s/temp", "v": 27.2, "u": "Cel" }
] ]
Req: POST /l/ (Content-Format: application/link-format) Req: POST /l/ (Content-Format: application/link-format)
</s/humidity> </s/humidity>
Res: 2.04 Changed Res: 2.04 Changed
Req: GET /l/ (Accept: application/link-format) Req: GET /l/ (Accept: application/link-format)
Res: 2.05 Content (application/link-format) Res: 2.05 Content (application/link-format)
</s/light>,</s/temp>,</s/humidity> </s/light>,</s/temp>,</s/humidity>
Req: GET /l/ Req: GET /l/
Res: 2.05 Content (application/senml+json) Res: 2.05 Content (application/senml+json)
[ [
{ "bn": "example.com/" },
{ "n": "/s/light", "v": 123, "u": "lx" }, { "n": "/s/light", "v": 123, "u": "lx" },
{ "n": "/s/temp", "v": 27.2, "u": "Cel" }, { "n": "/s/temp", "v": 27.2, "u": "Cel" },
{ "n": "/s/humidity", "v": 80, "u": "%RH" } { "n": "/s/humidity", "v": 80, "u": "%RH" }
] ]
Req: DELETE /l/ Req: DELETE /l/
Res: 2.02 Deleted Res: 2.02 Deleted
4.4. Sensor 4.4. Sensor
skipping to change at page 14, line 12 skipping to change at page 14, line 12
The following are examples of Sensor interface requests in both text/ The following are examples of Sensor interface requests in both text/
plain and application/senml+json. plain and application/senml+json.
Req: GET /s/humidity (Accept: text/plain) Req: GET /s/humidity (Accept: text/plain)
Res: 2.05 Content (text/plain) Res: 2.05 Content (text/plain)
80 80
Req: GET /s/humidity (Accept: application/senml+json) Req: GET /s/humidity (Accept: application/senml+json)
Res: 2.05 Content (application/senml+json) Res: 2.05 Content (application/senml+json)
[ [
{ "bn": "example.com/s/" },
{ "n": "humidity", "v": 80, "u": "%RH" } { "n": "humidity", "v": 80, "u": "%RH" }
] ]
4.5. Parameter 4.5. Parameter
The Parameter interface allows configurable parameters and other The Parameter interface allows configurable parameters and other
information to be modeled as a resource. The value of the parameter information to be modeled as a resource. The value of the parameter
can be read (GET) or update (PUT). Plain text or SenML Media types can be read (GET) or update (PUT). Plain text or SenML Media types
MAY be returned from this type of interface. MAY be returned from this type of interface.
skipping to change at page 15, line 37 skipping to change at page 15, line 38
5. Security Considerations 5. 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. Conversely, a malicious
client could attempt to write to arbitrary resources on a poorly
implemented server described in a linked batch.
6. 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.
6.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 an origin server. resources on an origin 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
6.2. Batch 6.2. Batch
skipping to change at page 17, line 51 skipping to change at page 18, line 7
Notes: None Notes: 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 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. Ari Keraenen provided updated SenML examples. document. Ari Keraenen provided updated SenML examples. Christian
Amsuss supplied a comprehensive review of draft -12.
8. Contributors 8. Contributors
Matthieu Vial Matthieu Vial
Schneider-Electric Schneider-Electric
Grenoble Grenoble
France France
Phone: +33 (0)47657 6522 Phone: +33 (0)47657 6522
EMail: matthieu.vial@schneider-electric.com EMail: matthieu.vial@schneider-electric.com
9. Changelog 9. Changelog
Changes from -12 to -13:
o SenML examples now use the Base Name (bn) labels from RFC 8428
o Security considerations discusses client misuse of linked batches
Changes from -11 to -12: Changes from -11 to -12:
o Removed all text referring to function sets/profiles o Removed all text referring to function sets/profiles
o Clarified list collections o Clarified list collections
o Content-formats for collections and items rectified o Content-formats for collections and items rectified
o Simplified Appendix A and removed Appendix B o Simplified Appendix A and removed Appendix B
skipping to change at page 22, line 8 skipping to change at page 22, line 25
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<https://www.rfc-editor.org/info/rfc6690>. <https://www.rfc-editor.org/info/rfc6690>.
[RFC8288] Nottingham, M., "Web Linking", RFC 8288, [RFC8288] Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017, DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/info/rfc8288>. <https://www.rfc-editor.org/info/rfc8288>.
10.2. Informative References 10.2. Informative References
[I-D.ietf-core-dynlink] [I-D.ietf-core-dynlink]
Shelby, Z., Vial, M., Koster, M., Groves, C., Zhu, J., and Shelby, Z., Koster, M., Groves, C., Zhu, J., and B.
B. Silverajan, "Dynamic Resource Linking for Constrained Silverajan, "Dynamic Resource Linking for Constrained
RESTful Environments", draft-ietf-core-dynlink-05 (work in RESTful Environments", draft-ietf-core-dynlink-06 (work in
progress), March 2018. progress), July 2018.
[I-D.ietf-core-resource-directory] [I-D.ietf-core-resource-directory]
Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. Shelby, Z., Koster, M., Bormann, C., Stok, P., and C.
Amsuess, "CoRE Resource Directory", draft-ietf-core- Amsuess, "CoRE Resource Directory", draft-ietf-core-
resource-directory-13 (work in progress), March 2018. resource-directory-15 (work in progress), October 2018.
[I-D.ietf-core-senml]
Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
Bormann, "Sensor Measurement Lists (SenML)", draft-ietf-
core-senml-16 (work in progress), May 2018.
[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 23, line 23 skipping to change at page 23, line 33
[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/RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014,
<https://www.rfc-editor.org/info/rfc7252>. <https://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,
<https://www.rfc-editor.org/info/rfc7396>. <https://www.rfc-editor.org/info/rfc7396>.
[RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
Bormann, "Sensor Measurement Lists (SenML)", RFC 8428,
DOI 10.17487/RFC8428, August 2018,
<https://www.rfc-editor.org/info/rfc8428>.
Appendix A. Current Usage of Interfaces Appendix A. Current Usage of Interfaces
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 and interfaces. This should be definition and use of collections and interfaces. This should be
considered when considering the scope of this document. considered when considering the scope of this document.
A.1. Constrained RESTful Environments (CoRE) Link Format (IETF) A.1. Constrained RESTful Environments (CoRE) Link Format (IETF)
 End of changes. 20 change blocks. 
25 lines changed or deleted 37 lines changed or added

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