Internet DRAFT - draft-vial-core-link-format-wadl

draft-vial-core-link-format-wadl






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.

   <application xmlns="http://wadl.dev.java.net/2009/02"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://wadl.dev.java.net/2009/02 wadl.xsd">
     <resource_type id="sensor.temperature">
       <method name="GET">
         <doc>GetTemperature</doc>
         <response>
           <representation mediaType="text/plain" />
         </response>
       </method>
     </resource_type>
     <resource_type id="parameter.threshold">
       <method name="PUT">
         <doc>SetThreshold</doc>
         <request>
           <representation mediaType="text/plain" />
         </request>
       </method>
    </resource_type>
   </application>

                  Home Automation WADL sample (ha1.wadl)

                                 Figure 1






















Vial & Shelby             Expires March 4, 2012                 [Page 6]

Internet-Draft            Link Format and WADL                 Sept 2011


 <application xmlns="http://wadl.dev.java.net/2009/02"
 xmlns:em2="http://www.example.org/EnergyManagement/2"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://wadl.dev.java.net/2009/02 wadl.xsd">
   <grammars>
     <include href="http://www.example.org/EnergyManagement/2/em2.xsd"/>
   </grammars>
   <resource_type id="meter.power">
     <method name="GET">
       <doc>GetPower</doc>
       <response>
       <representation mediaType="application/xml" element="em2:Power"/>
       </response>
     </method>
   </resource_type>
   <resource_type id="parameter.threshold">
     <method name="PUT">
       <doc>SetThreshold</doc>
       <request>
   <representation mediaType="application/xml" element="em2:Threshold"/>
       </request>
     </method>
   </resource_type>
 </application>

                 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
   </tmp>;rt="AirTemperature";
   if="http://www.example.org/ha1.wadl#sensor.temperature",
   </tmp/thr>;rt="TemperatureAlarm";
   if="http://www.example.org/ha1.wadl#parameter.threshold"
   </pwr>;rt="PowerConsumption";
   if="http://www.example.org/em2.wadl#meter.power",
   </pwr/thr>;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
   </tmp>;rt="AirTemperature";if="ha1.wadl#sensor.temperature",
   </tmp/thr>;rt="TemperatureAlarm";if="ha1.wadl#parameter.threshold"
   </pwr>;rt="PowerConsumption";if="em2.wadl#meter.power",
   </pwr/thr>;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
   </tmp>;rt="AirTemperature";if="sensor.temperature",
   </thr>;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


   <application xmlns="http://wadl.dev.java.net/2009/02"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://wadl.dev.java.net/2009/02 wadl.xsd">
     <resource_type id="sensor.temperature">
       <method name="GET">
         <doc>GetTemperature</doc>
         <request>
           <param name="unit" style="query" default="C" required="no">
             <option value="C"><doc>Celsius</doc></option>
             <option value="K"><doc>Kelvin</doc></option>
             <option value="F"><doc>Farenheit</doc></option>
           </param>
         </request>
         <response>
           <representation mediaType="text/plain" />
         <response>
       </method>
     </resource_type>
   </application>

                  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
   </tmp>;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
   </tmp>;rt="DryBulbTemperature";if="sensor.temperature",
   </eff>;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


   <application xmlns="http://wadl.dev.java.net/2009/02"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:app="http://www.example.org/2011/app"
   xsi:schemaLocation="http://wadl.dev.java.net/2009/02 wadl.xsd">
     <grammars>
       <include href="http://www.example.org/2011/app/app.xsd"/>
     </grammars>
     <resource_type id="list.alarms">
       <method name="GET">
         <doc>GetAlarmList</doc>
         <response>
           <representation mediaType="application/link-format"/>
         </response>
       </method>
       <method name="POST">
         <doc>AddAlarm</doc>
         <request>
           <representation mediaType="application/xml"
               element="Alarm"/>
         </request>
       </method>
       <resource path="{alarmId}">
         <param name="alarmId" style="template" type="xsd:int"/>
         <method name="GET">
           <doc>GetAlarm</doc>
           <response>
             <representation mediaType="application/xml"
                 element="app:Alarm"/>
           </response>
         </method>
         <method name="DELETE">
           <doc>RemoveAlarm</doc>
           <request>
           </request>
         </method>
       </resource>
     </resource_type>
   </application>

                  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
   </tmp>;rt="DryBulbTemperature";if="sensor.temperature",
   </alrm>;rt="TemperatureAlarms";if="list.alarms",

   REQ: GET /alrm
   RES: 2.00 OK
   </alrm/1>,
   </alrm/2>

   REQ: GET /alrm/1
   RES: 2.00 OK
   <Alarm time="" type="GreaterThan" threshold="28" />


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,
              <http://www.w3.org/TR/2011/PR-exi-20110120/>.

   [wadl]     Hadley, M., "Web Application Description Language (WADL)",
              2009, <http://java.net/projects/wadl/sources/svn/content/
              trunk/www/wadl20090202.pdf>.

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]