Constrained RESTful Environments M. Vial Internet-Draft Schneider-Electric Intended status: Informational Z. Shelby Expires: March 4, 2012 Sensinode Sept 2011 Interface description with WADL in CoRE draft-vial-core-link-format-wadl-01 Abstract This document provides guidelines to use the Web Application Description Language (WADL) in Constrained RESTful environments. The document mainly focuses on how to combine WADL with the CoRE Link Format to describe a REST interface. Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. 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." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on March 4, 2012. Copyright Notice Copyright (c) 2011 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 (http://trustee.ietf.org/license-info) in effect on the date of Vial & Shelby Expires March 4, 2012 [Page 1] Internet-Draft Link Format and WADL Sept 2011 publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 3. WADL in a CoRE environment . . . . . . . . . . . . . . . . . . 3 3.1. CoAP adaptations . . . . . . . . . . . . . . . . . . . . . 3 3.1.1. Methods . . . . . . . . . . . . . . . . . . . . . . . 4 3.1.2. Status code . . . . . . . . . . . . . . . . . . . . . 4 3.1.3. HTTP header parameters . . . . . . . . . . . . . . . . 4 3.2. CoRE resources . . . . . . . . . . . . . . . . . . . . . . 4 3.3. Semantic description . . . . . . . . . . . . . . . . . . . 5 3.4. Binary XML format . . . . . . . . . . . . . . . . . . . . 5 4. Use cases . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.1. WADL resource type identifiers . . . . . . . . . . . . . . 5 4.2. Description of query parameters . . . . . . . . . . . . . 8 4.3. Interface description and associated semantic . . . . . . 10 4.4. Collection of resources . . . . . . . . . . . . . . . . . 10 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 7. Security Considerations . . . . . . . . . . . . . . . . . . . 12 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 8.1. Normative References . . . . . . . . . . . . . . . . . . . 12 8.2. Informative References . . . . . . . . . . . . . . . . . . 13 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 Vial & Shelby Expires March 4, 2012 [Page 2] Internet-Draft Link Format and WADL Sept 2011 1. Introduction The Constrained RESTful Environments (CoRE) working group aims at providing a comprehensive suite of standards that will make it possible to build a REST architecture for M2M applications with highly constrained nodes and networks. The CoRE Link Format [I-D.ietf-core-link-format] which is part of this suite defines a format to be used by CoAP servers to list hosted resources using the Web linking technique defined in RFC 5988 [RFC5988]. More specically the 'if' attribute of Link Format allows an interface designer indicate a description of the behavior, the parameters, the representation and eventually the set of sub- resources associated to a given CoRE resource. One way to describe the interface to a resource is using the Web Application Description Language (WADL). The first part of this document will explain how to benefit from WADL to describe the REST interface of CoRE resources. Then the second part of the document will show how the previous guidelines are applied in different use cases. The reader should keep in mind that this document does not suggest in any way constrained nodes would be able to retrieve and parse a WADL description. The interface description is rather considered as documentation with a standard and machine-processable language that will help implementors to understand an interface and eventually generate stub code. 2. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. 3. WADL in a CoRE environment 3.1. CoAP adaptations The WADL language is primilarily designed to describe HTTP-based web applications. WADL is not strongly tied to the HTTP protocol [RFC2616] and any HTTP-like web protocol can be described with WADL. In a CoRE environment the CoAP protocol [I-D.ietf-core-coap] is deployed in place of the HTTP protocol as an optimized web transfer protocol. An interface designer must take into consideration the specifity of CoAP while writing the WADL definition. Vial & Shelby Expires March 4, 2012 [Page 3] Internet-Draft Link Format and WADL Sept 2011 3.1.1. Methods CoAP only supports a subset of HTTP methods. So a WADL description deployed in a CoRE environment MUST only make use of methods available in CoAP namely GET, PUT, POST and DELETE. 3.1.2. Status code CoAP decorrelates the response code representation from the actual value of the code. Hence the response code 2.00 has the value 64. When a CoAP response code is associated to the description of a response in WADL, it is RECOMMENDED to use the response code labels. 3.1.3. HTTP header parameters CoAP does not support user-defined options in the base specification. So as a rule of thumb, header parameters are discouraged with CoAP. 3.2. CoRE resources The WADL language describes a REST resource with a resource element which associates a REST behavior to a URI. WADL offers language elements to describe the following aspects of a REST behavior: allowed methods, query string parameters, media type of the request and response content, URI of the resource and the subordinate resources. The description of the behavior can either be a reference to a resource_type element or child elements if the description is inline. When WADL is combined with the CoRE Link Format it is RECOMMENDED to write definitions with resource_type elements. Then a Web link can reference a resource_type with the Interface Description 'if' attribute. So a Web link plays the same role as the resource element of WADL in the sense that the Web link instantiates a resource_type by linking it to an URI. Because the resource_type element is referenced outside of the WADL description, the rules of section 2.5.1 in WADL [wadl] are not applicable. Instead the target URI of the Web link where the resource_type element is referenced MUST be used as the base URI to construct each child resource identifiers. The 'if' attribute of a Web link SHOULD reference a resource_type AND a WADL document to avoid potential ambiguities. resource_type elements are identified by their XML id. The 'if' attribute MAY take the form of an URI. The path of the URI specify the WADL document while the fragment part of the URI points to a resource_type. The full URI notation may add significant overhead in a link format Vial & Shelby Expires March 4, 2012 [Page 4] Internet-Draft Link Format and WADL Sept 2011 description thus several formats are acceptable depending on the risk of identifier conflicts. Here are few examples of 'if' attributes. o http://www.example.org/interface.wadl#resourceType o interface.wadl#resourceType o resourceType 3.3. Semantic description The main goal of the WADL description in a CoRE environment is to describe the actions that can be performed on a REST resource. The WADL document may include a grammar element with a schema to offer a detailed description of data representations hence semantically refining the description. But this mechanism is not applicable to all data representations especially if the data is not XML-based. Moreover the interface description is not meant to be directly interpreted by CoRE nodes. Thus it is RECOMMENDED to associate the semantic description of a resource with a resource type 'rt' attribute without relying only on the 'if' attribute. This separation of concerns allows an interface designer to reuse the same interface description for resources that grasp different concepts. 3.4. Binary XML format Because CoRE deals with constrained networks, traditional XML data representations may be superseded with a more compact format for the XML information set. Efficient XML Interchange [exi] is an example of such binary XML format which heavily relies on a XML schema to achieve the best compression performances. The schema identifier can be carried inline with the binary stream or specified out-of-band. If there is no schema identifier present in the data stream but the WADL definition of the representation has a reference to grammar element, one MUST assume that the data stream is schema-informed. 4. Use cases 4.1. WADL resource type identifiers Let's consider an organization which has defined two application profiles in two separate WADL documents. The first profile targets Home Automation applications while the second deals with Energy Management. One CoRE device may implement REST services from both profiles. The WADL descriptions are versioned to support future evolutions of Vial & Shelby Expires March 4, 2012 [Page 5] Internet-Draft Link Format and WADL Sept 2011 the interface. The profiles have a class/type structure with a dot notation for REST resource types. They also share some concepts but with different implementations. Figure 1 and Figure 2 are short extracts of possible WADL descriptions for such profiles. GetTemperature SetThreshold Home Automation WADL sample (ha1.wadl) Figure 1 Vial & Shelby Expires March 4, 2012 [Page 6] Internet-Draft Link Format and WADL Sept 2011 GetPower SetThreshold Energy Management WADL sample (em2.wadl) Figure 2 In a home network, the devices share the same infrastructure but usually come from different vendors and may implement many application profiles. In this context it is useful to reference a WADL interface with an absolute URI. REQ: GET /.well-known/core RES: 2.00 OK ;rt="AirTemperature"; if="http://www.example.org/ha1.wadl#sensor.temperature", ;rt="TemperatureAlarm"; if="http://www.example.org/ha1.wadl#parameter.threshold" ;rt="PowerConsumption"; if="http://www.example.org/em2.wadl#meter.power", ;rt="PowerAlarm"; if="http://www.example.org/em2.wadl#parameter.threshold" If a deployment of devices is known to implement only REST services from one organization the resource_type identifiers may be shortened. It is however indispensable to clearly indicate a WADL document Vial & Shelby Expires March 4, 2012 [Page 7] Internet-Draft Link Format and WADL Sept 2011 because the resource_type identifiers are only unique within a single WADL document. The example below reflects how these assumptions are actually applied. REQ: GET /.well-known/core RES: 2.00 OK ;rt="AirTemperature";if="ha1.wadl#sensor.temperature", ;rt="TemperatureAlarm";if="ha1.wadl#parameter.threshold" ;rt="PowerConsumption";if="em2.wadl#meter.power", ;rt="PowerAlarm";if="em2.wadl#parameter.threshold" If the network is dedicated to a specific application profile it is acceptable to omit the reference to the WADL description which is supposed to be known out-of-band. Web links may have the following format: REQ: GET /.well-known/core RES: 2.00 OK ;rt="AirTemperature";if="sensor.temperature", ;rt="TemperatureAlarm";if="parameter.threshold" 4.2. Description of query parameters A typical usage of WADL is to provide a detailed description of how a client can build the query string component of a URI to access a parametrized resource. Below is an example that describes how a client can select the unit for a temperature sensor. Vial & Shelby Expires March 4, 2012 [Page 8] Internet-Draft Link Format and WADL Sept 2011 GetTemperature Definition of an optional query string Figure 3 This description give information about four valid URIs that are exposed in the following CoAP exchange. REQ: GET /.well-known/core RES: 2.00 OK ;if="sensor.temperature" REQ: GET /tmp RES: 2.00 OK 20 REQ: GET /tmp?unit=C RES: 2.00 OK 20 REQ: GET /tmp?unit=K RES: 2.00 OK 293.15 REQ: GET /tmp?unit=F RES: 2.00 OK 68 Vial & Shelby Expires March 4, 2012 [Page 9] Internet-Draft Link Format and WADL Sept 2011 4.3. Interface description and associated semantic The same interface description can often be reused for similar but distinct concepts. For example a temperature sensor may be able to produce the traditional air temperature but also the effective temperature which is a combination of air temperature and wind speed. Then the definition in Figure 3 is valid for both concepts and the device description could look like depicted below. REQ: GET /.well-known/core RES: 2.00 OK ;rt="DryBulbTemperature";if="sensor.temperature", ;rt="EffectiveTemperature";if="sensor.temperature" 4.4. Collection of resources Repeating an interface definition attribute with the same identifier for a collection of resources is especially inefficient and laborious with link format. Hopefully WADL supports templated path definitions to describe sub-resources. The template style of parameters allows an interface designer to specify the dynamic path elements of a URI thanks to a curly brace notation. It is also possible to precisely determine the data type associated to a variable path element. Below is an example of how a list of pending alarms can be described with this feature. Vial & Shelby Expires March 4, 2012 [Page 10] Internet-Draft Link Format and WADL Sept 2011 GetAlarmList AddAlarm GetAlarm RemoveAlarm Definition of a collection of resources Figure 4 Then the resource_type is referenced only once but provides an interface description for the whole collection of resources. Vial & Shelby Expires March 4, 2012 [Page 11] Internet-Draft Link Format and WADL Sept 2011 REQ: GET /.well-known/core RES: 2.00 OK ;rt="DryBulbTemperature";if="sensor.temperature", ;rt="TemperatureAlarms";if="list.alarms", REQ: GET /alrm RES: 2.00 OK , REQ: GET /alrm/1 RES: 2.00 OK 5. Acknowledgements Thanks to Linyi Tian for its feedback on the document. 6. IANA Considerations This document requests no actions from IANA. 7. Security Considerations This document has no known security implications. 8. References 8.1. Normative References [I-D.ietf-core-coap] Shelby, Z., Hartke, K., Bormann, C., and B. Frank, "Constrained Application Protocol (CoAP)", draft-ietf-core-coap-07 (work in progress), July 2011. [I-D.ietf-core-link-format] Shelby, Z., "CoRE Link Format", draft-ietf-core-link-format-07 (work in progress), July 2011. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. Vial & Shelby Expires March 4, 2012 [Page 12] Internet-Draft Link Format and WADL Sept 2011 [exi] W3C, "Efficient XML Interchange (EXI) Format 1.0", 2011, . [wadl] Hadley, M., "Web Application Description Language (WADL)", 2009, . 8.2. Informative References [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Authors' Addresses Matthieu Vial Schneider-Electric Grenoble, FRANCE Phone: +33 (0)47657 6522 Email: matthieu.vial@schneider-electric.com Zach Shelby Sensinode Kidekuja 2 Vuokatti 88600 FINLAND Phone: +358407796297 Email: zach@sensinode.com Vial & Shelby Expires March 4, 2012 [Page 13]