--- 1/draft-ietf-core-interfaces-12.txt 2018-10-22 05:14:19.538740034 -0700 +++ 2/draft-ietf-core-interfaces-13.txt 2018-10-22 05:14:19.586741177 -0700 @@ -1,25 +1,25 @@ CoRE Working Group Z. Shelby Internet-Draft ARM Intended status: Informational M. Koster -Expires: December 29, 2018 SmartThings +Expires: April 25, 2019 SmartThings C. Groves J. Zhu Huawei B. Silverajan, Ed. Tampere University of Technology - June 27, 2018 + October 22, 2018 Reusable Interface Definitions for Constrained RESTful Environments - draft-ietf-core-interfaces-12 + draft-ietf-core-interfaces-13 Abstract This document defines a set of Constrained RESTful Environments (CoRE) Link Format Interface Descriptions [RFC6690] applicable for use in constrained environments. These include the: Actuator, Parameter, Read-only parameter, Sensor, Batch, Linked Batch and Link List interfaces. The Batch, Linked Batch and Link List interfaces make use of resource @@ -44,21 +44,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on December 29, 2018. + This Internet-Draft will expire on April 25, 2019. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -88,45 +88,45 @@ 4.4. Sensor . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.5. Parameter . . . . . . . . . . . . . . . . . . . . . . . . 14 4.6. Read-only Parameter . . . . . . . . . . . . . . . . . . . 14 4.7. Actuator . . . . . . . . . . . . . . . . . . . . . . . . 14 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 6.1. Link List . . . . . . . . . . . . . . . . . . . . . . . . 15 6.2. Batch . . . . . . . . . . . . . . . . . . . . . . . . . . 16 6.3. Linked Batch . . . . . . . . . . . . . . . . . . . . . . 16 6.4. Sensor . . . . . . . . . . . . . . . . . . . . . . . . . 16 - 6.5. Parameter . . . . . . . . . . . . . . . . . . . . . . . . 16 + 6.5. Parameter . . . . . . . . . . . . . . . . . . . . . . . . 17 6.6. Read-only parameter . . . . . . . . . . . . . . . . . . . 17 6.7. Actuator . . . . . . . . . . . . . . . . . . . . . . . . 17 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 18 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 18 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 - 10.1. Normative References . . . . . . . . . . . . . . . . . . 21 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 22 10.2. Informative References . . . . . . . . . . . . . . . . . 22 Appendix A. Current Usage of Interfaces . . . . . . . . . . . . 23 A.1. Constrained RESTful Environments (CoRE) Link Format (IETF) . . . . . . . . . . . . . . . . . . . . . . . . . 23 - A.2. Open Connectivity Foundation (OCF) . . . . . . . . . . . 23 + A.2. Open Connectivity Foundation (OCF) . . . . . . . . . . . 24 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 1. Introduction IETF Standards for machine to machine communication in constrained environments describe a REST protocol and a set of related information standards that may be used to represent machine data and machine metadata in REST interfaces. CoRE Link-format is a standard for doing Web Linking [RFC8288] in constrained environments. SenML - [I-D.ietf-core-senml] is a simple data model and representation - format for composite and complex structured resources. CoRE Link- - Format and SenML can be used by CoAP [RFC7252] or HTTP servers. + [RFC8428] is a simple data model and representation format for + composite and complex structured resources. CoRE Link-Format and + SenML can be used by CoAP [RFC7252] or HTTP servers. The discovery of resources offered by a constrained server is very important in machine-to-machine applications where there are no humans in the loop. Machine application clients must be able to adapt to different resource organizations without advance knowledge of the specific data structures hosted by each connected thing. The use of Web Linking for the description and discovery of resources hosted by constrained origin servers is specified by CoRE Link Format [RFC6690]. CoRE Link Format additionally defines a link attribute for interface description ("if") that can be used to describe the @@ -453,21 +453,21 @@ Note: The use of an Accept option with application/link-format is recommended even though it is not strictly needed for the Link List interface because this interface is extended by the batch and linked batch interfaces where different content-formats are possible. The request returns a list of URI references with absolute paths to the resources as defined in CoRE Link Format. This interface is typically used with a parent resource to enumerate sub-resources but 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. Req: GET /d/ (Accept:application/link-format) Res: 2.05 Content (application/link-format) ;rt="simple.dev.n";if="core.p", ;rt="simple.dev.mdl";if="core.rp" 4.2. Batch The Batch interface is used to manipulate a collection of sub- @@ -480,20 +480,21 @@ 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 order to support multiple sub-resources. The following example interacts with a Batch /s/ with Sensor sub- resources /s/light, /s/temp and /s/humidity. Req: GET /s/ Res: 2.05 Content (application/senml+json) [ + { "bn": "example.com/s/" }, { "n": "light", "v": 123, "u": "lx" }, { "n": "temp", "v": 27.2, "u": "Cel" }, { "n": "humidity", "v": 80, "u": "%RH" } ] 4.3. Linked Batch The Linked Batch interface is an extension of the Batch interface. Contrary to the basic Batch which is a collection statically defined by the origin server, a Linked Batch is dynamically controlled by a @@ -509,35 +510,37 @@ The following example interacts with a Linked Batch /l/ and creates a collection containing /s/light, /s/temp and /s/humidity in 2 steps. Req: POST /l/ (Content-Format: application/link-format) , Res: 2.04 Changed Req: GET /l/ Res: 2.05 Content (application/senml+json) [ + { "bn": "example.com/" }, { "n": "/s/light", "v": 123, "u": "lx" }, { "n": "/s/temp", "v": 27.2, "u": "Cel" } ] Req: POST /l/ (Content-Format: application/link-format) Res: 2.04 Changed Req: GET /l/ (Accept: application/link-format) Res: 2.05 Content (application/link-format) ,, Req: GET /l/ Res: 2.05 Content (application/senml+json) [ + { "bn": "example.com/" }, { "n": "/s/light", "v": 123, "u": "lx" }, { "n": "/s/temp", "v": 27.2, "u": "Cel" }, { "n": "/s/humidity", "v": 80, "u": "%RH" } ] Req: DELETE /l/ Res: 2.02 Deleted 4.4. Sensor @@ -552,20 +555,21 @@ The following are examples of Sensor interface requests in both text/ plain and application/senml+json. Req: GET /s/humidity (Accept: text/plain) Res: 2.05 Content (text/plain) 80 Req: GET /s/humidity (Accept: application/senml+json) Res: 2.05 Content (application/senml+json) [ + { "bn": "example.com/s/" }, { "n": "humidity", "v": 80, "u": "%RH" } ] 4.5. Parameter The Parameter interface allows configurable parameters and other 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 MAY be returned from this type of interface. @@ -626,31 +630,32 @@ 5. Security Considerations An implementation of a client needs to be prepared to deal with responses to a request that differ from what is specified in this document. A server implementing what the client thinks is a resource with one of these interface descriptions could return malformed representations and response codes either by accident or maliciously. A server sending maliciously malformed responses could attempt to take advantage of a poorly implemented client for example to crash - the node or perform denial of service. + 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 This document registers the following CoRE Interface Description (if=) Link Target Attribute Values. 6.1. Link List Attribute Value: core.ll - Description: The Link List interface is used to retrieve a list of resources on an origin server. Reference: This document. Note to RFC Editor - please insert the appropriate RFC reference. Notes: None 6.2. Batch @@ -733,34 +739,41 @@ Notes: None 7. Acknowledgements Acknowledgement is given to colleagues from the SENSEI project who were critical in the initial development of the well-known REST interface concept, to members of the IPSO Alliance where further requirements for interface descriptions have been discussed, and to Szymon Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have provided useful discussion and input to the concepts in this - document. Ari Keraenen provided updated SenML examples. + document. Ari Keraenen provided updated SenML examples. Christian + Amsuss supplied a comprehensive review of draft -12. 8. Contributors Matthieu Vial Schneider-Electric Grenoble France Phone: +33 (0)47657 6522 EMail: matthieu.vial@schneider-electric.com 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: o Removed all text referring to function sets/profiles o Clarified list collections o Content-formats for collections and items rectified o Simplified Appendix A and removed Appendix B @@ -931,34 +944,29 @@ Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, . [RFC8288] Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, October 2017, . 10.2. Informative References [I-D.ietf-core-dynlink] - Shelby, Z., Vial, M., Koster, M., Groves, C., Zhu, J., and - B. Silverajan, "Dynamic Resource Linking for Constrained - RESTful Environments", draft-ietf-core-dynlink-05 (work in - progress), March 2018. + Shelby, Z., Koster, M., Groves, C., Zhu, J., and B. + Silverajan, "Dynamic Resource Linking for Constrained + RESTful Environments", draft-ietf-core-dynlink-06 (work in + progress), July 2018. [I-D.ietf-core-resource-directory] Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. Amsuess, "CoRE Resource Directory", draft-ietf-core- - resource-directory-13 (work in progress), March 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. + resource-directory-15 (work in progress), October 2018. [OIC-Core] "OIC Resource Type Specification v1.1.0", 2016, . [OIC-SmartHome] "OIC Smart Home Device Specification v1.1.0", 2016, . [OMA-TS-LWM2M] @@ -992,20 +1000,25 @@ [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014, . [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, DOI 10.17487/RFC7396, October 2014, . + [RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. + Bormann, "Sensor Measurement Lists (SenML)", RFC 8428, + DOI 10.17487/RFC8428, August 2018, + . + Appendix A. Current Usage of Interfaces Editor's note: This appendix will be removed. It is only included for information. This appendix analyses the current landscape with regards the definition and use of collections and interfaces. This should be considered when considering the scope of this document. A.1. Constrained RESTful Environments (CoRE) Link Format (IETF)