One document matched: draft-vial-core-link-format-wadl-00.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!-- This template is for creating an Internet Draft using xml2rfc,
which is available here: http://xml.resource.org. -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
There has to be one entity for each item to be referenced.
An alternate method (rfc include) is described in the references. -->
<!ENTITY RFC3406 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3406.xml">
<!ENTITY RFC2141 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2141.xml">
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2616 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!ENTITY RFC5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
<!ENTITY I-D.ietf-core-link-format SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-link-format.xml">
<!ENTITY I-D.ietf-core-coap SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-coap.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!-- For a complete list and description of processing instructions (PIs),
please see http://xml.resource.org/authoring/README.html. -->
<!-- Below are generally applicable Processing Instructions (PIs) that most I-Ds might want to use.
(Here they are set differently than their defaults in xml2rfc v1.32) -->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="3"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!-- control vertical white space
(using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="info" docName="draft-vial-core-link-format-wadl-00" ipr="trust200902">
<!-- category values: std, bcp, info, exp, and historic
ipr values: full3667, noModification3667, noDerivatives3667
you can add the attributes updates="NNNN" and obsoletes="NNNN"
they will automatically be output with "(if approved)" -->
<!-- ***** FRONT MATTER ***** -->
<front>
<!-- The abbreviated title is used in the page header - it is only necessary if the
full title is longer than 39 characters -->
<title abbrev="Link Format and WADL">Interface description with WADL in CoRE</title>
<!-- add 'role="editor"' below for the editors if appropriate -->
<!-- Another author who claims to be an editor -->
<author fullname="Matthieu Vial" initials="M.V."
surname="Vial">
<organization>Schneider-Electric</organization>
<address>
<postal>
<street></street>
<!-- Reorder these if your country does things differently -->
<city>Grenoble</city>
<region></region>
<code></code>
<country>FRANCE</country>
</postal>
<phone>+33 (0)47657 6522</phone>
<email>matthieu.vial@schneider-electric.com</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<author initials="Z" surname="Shelby" fullname="Zach Shelby">
<organization>
Sensinode
</organization>
<address>
<postal>
<street>Kidekuja 2</street>
<city>Vuokatti</city>
<code>88600</code>
<country>FINLAND</country>
</postal>
<phone>+358407796297</phone>
<email>zach@sensinode.com</email>
</address>
</author>
<date month="March" year="2011" />
<!-- If the month and year are both specified and are the current ones, xml2rfc will fill
in the current day for you. If only the current year is specified, xml2rfc will fill
in the current day and month for you. If the year is not the current one, it is
necessary to specify at least a month (xml2rfc assumes day="1" if not specified for the
purpose of calculating the expiry date). With drafts it is normally sufficient to
specify just the year. -->
<!-- Meta-data Declarations -->
<area>General</area>
<workgroup>Constrained RESTful Environments</workgroup>
<!-- WG name at the upperleft corner of the doc,
IETF is fine for individual submissions.
If this element is not present, the default is "Network Working Group",
which is used by the RFC Editor as a nod to the history of the IETF. -->
<keyword>WADL</keyword>
<keyword>REST</keyword>
<keyword>M2M</keyword>
<keyword>Web linking</keyword>
<!-- Keywords will be incorporated into HTML output
files in a meta tag but they have no effect on text or nroff
output. If you submit your draft to the RFC Editor, the
keywords will be used for the search engine. -->
<abstract>
<t>This document provides guidelines to use the Web Application
Description Language (WADL) in Constrained RESTful environments.
The document mainly focus on how to combine WADL with the
CoRE Link Format to describe a REST interface.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>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.</t>
<t>The <xref target="I-D.ietf-core-link-format">CoRE Link Format</xref> 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 <xref target="RFC5988">
RFC 5988</xref>. More specically the 'd' 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).</t>
<t>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.</t>
<t>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.</t>
</section>
<section title="Requirements Language">
<t>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 <xref
target="RFC2119">RFC 2119</xref>.</t>
</section>
<section anchor="wadl_core" title="WADL in a CoRE environment">
<section anchor="adaptation" title="CoAP adaptations">
<t>The WADL language is primilarily designed to describe HTTP-based web applications. WADL is
not strongly tied to the <xref target="RFC2616">HTTP protocol</xref> and any HTTP-like web
protocol can be described with WADL. In a CoRE environment the <xref target="I-D.ietf-core-coap">
CoAP protocol</xref> 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.</t>
<section anchor="methods" title="Methods">
<t>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.</t>
</section>
<section anchor="status" title="Status code">
<t>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.</t>
</section>
<section anchor="http_header" title="HTTP header parameters">
<t>CoAP does not support user-defined options in the base specification.
So as a rule of thumb, header parameters are discouraged with CoAP.</t>
</section>
<section anchor="multi_repr" title="Mutliple representations">
<t>CoAP does not support content negotiation so only one media type can be associated
to a request or a response.</t>
</section>
</section>
<section anchor="resources" title="CoRE resources">
<t>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.</t>
<t>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 'd' 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.</t>
<t>Because the resource_type element is referenced outside of the WADL description, the rules of
section 2.5.1 in <xref target="wadl">WADL</xref> 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.</t>
<t>The 'd' 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 'd' 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 description thus several formats are acceptable
depending on the risk of identifier conflicts. Here are few examples of 'd' attributes.</t>
<t><list style="symbols">
<t>http://www.example.org/interface.wadl#resourceType</t>
<t>interface.wadl#resourceType</t>
<t>resourceType</t>
</list></t>
</section>
<section anchor="semantic" title="Semantic description">
<t>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 'n' attribute without relying only on
the 'd' attribute. This separation of concerns allows an interface designer
to reuse the same interface description for resources that grasp different
concepts.</t>
</section>
<section anchor="binary_xml" title="Binary XML format">
<t>Because CoRE deals with constrained networks, traditional XML data representations may
be superseded with a more compact format for the XML information set.
<xref target="exi">Efficient XML Interchange</xref> 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.</t>
</section>
</section>
<section anchor="usecases" title="Use cases">
<section anchor="uc_identifier" title="Resource type identifiers">
<t>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.</t>
<t>The WADL descriptions are versioned to support future evolutions of 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. <xref target="figure1"/> and
<xref target="figure2"/> are short extracts of possible
WADL descriptions for such profiles.</t>
<figure align="center" anchor="figure1">
<artwork align="left"><![CDATA[
<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" id="GetTemperature">
<request>
<representation mediaType="text/plain" />
</request>
</method>
</resource_type>
<resource_type id="parameter.threshold">
<method name="PUT" id="SetThreshold>
<request>
<representation mediaType="text/plain" />
</request>
</method>
</resource_type>
</application>
]]></artwork>
<postamble>Home Automation WADL sample (ha1.wadl)</postamble>
</figure>
<figure align="center" anchor="figure2">
<artwork align="left"><![CDATA[
<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="meter.power">
<method name="GET" id="GetPower">
<request>
<representation mediaType="application/xml" />
</request>
</method>
</resource_type>
<resource_type id="parameter.threshold">
<method name="PUT" id="SetThreshold>
<request>
<representation mediaType="application/xml" />
</request>
</method>
</resource_type>
</application>
]]></artwork>
<postamble>Energy Management WADL sample (em2.wadl)</postamble>
</figure>
<t>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.</t>
<figure>
<artwork align="left"><![CDATA[
REQ: GET /.well-known/core
RES: 2.00 OK
</tmp>;n="AirTemperature";
d="http://www.example.org/ha1.wadl#sensor.temperature",
</tmp/thr>;n="TemperatureAlarm";
d="http://www.example.org/ha1.wadl#parameter.threshold"
</pwr>;n="PowerConsumption";
d="http://www.example.org/em2.wadl#meter.power",
</pwr/thr>;n="PowerAlarm";
d="http://www.example.org/em2.wadl#parameter.threshold"
]]></artwork>
</figure>
<t>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 because the resource_type identifiers are only unique within
a single WADL document. The example below reflects how these assumptions
are actually applied.</t>
<figure>
<artwork align="left"><![CDATA[
REQ: GET /.well-known/core
RES: 2.00 OK
</tmp>;n="AirTemperature";d="ha1.wadl#sensor.temperature",
</tmp/thr>;n="TemperatureAlarm";d="ha1.wadl#parameter.threshold"
</pwr>;n="PowerConsumption";d="em2.wadl#meter.power",
</pwr/thr>;n="PowerAlarm";d="em2.wadl#parameter.threshold"
]]></artwork>
</figure>
<t>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:</t>
<figure>
<artwork align="left"><![CDATA[
REQ: GET /.well-known/core
RES: 2.00 OK
</tmp>;n="AirTemperature";d="sensor.temperature",
</thr>;n="TemperatureAlarm";d="parameter.threshold"
]]></artwork>
</figure>
</section>
<section anchor="uc_query" title="Description of query parameters">
<t>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.</t>
<figure align="center" anchor="figure3">
<artwork align="left"><![CDATA[
<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" id="GetTemperature">
<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>
</method>
</resource_type>
</application>
]]></artwork>
<postamble>Definition of an optional query string</postamble>
</figure>
<t>This description give information about four valid URIs that are
exposed in the following CoAP exchange.</t>
<figure>
<artwork align="left"><![CDATA[
REQ: GET /.well-known/core
RES: 2.00 OK
</tmp>;d="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
]]></artwork>
</figure>
</section>
<section anchor="uc_semantic" title="Interface description and associated semantic">
<t>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 <xref target="figure3"/>
is valid for both concepts and the device description could look like depicted below.</t>
<figure>
<artwork align="left"><![CDATA[
REQ: GET /.well-known/core
RES: 2.00 OK
</tmp>;n="DryBulbTemperature";d="sensor.temperature",
</eff>;n="EffectiveTemperature";d="sensor.temperature"
]]></artwork>
</figure>
</section>
<section anchor="uc_collection" title="Collection of resources">
<t>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.</t>
<figure align="center" anchor="figure4">
<artwork align="left"><![CDATA[
<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"
xsi:schemaLocation="http://wadl.dev.java.net/2009/02 wadl.xsd">
<resource_type id="list.alarms">
<method name="GET" id="GetAlarmList">
<request>
</request>
<response>
<representation mediaType="application/link-format"/>
</response>
</method>
<method name="POST" id="AddAlarm">
<request>
<representation mediaType="application/xml"
element="Alarm"/>
</request>
</method>
<resource path="{alarmId}">
<param name="alarmId" style="template" type="xsd:int"/>
<method name="GET" id="GetAlarm">
<request>
</request>
<response>
<representation mediaType="application/xml"
element="Alarm"/>
</response>
</method>
<method name="DELETE" id="RemoveAlarm">
<request>
</request>
</method>
</resource>
</resource_type>
</application>
]]></artwork>
<postamble>Definition of a collection of resources</postamble>
</figure>
<t>Then the resource_type is referenced only once but provides an interface
description for the whole collection of resources.</t>
<figure>
<artwork align="left"><![CDATA[
REQ: GET /.well-known/core
RES: 2.00 OK
</tmp>;n="DryBulbTemperature";d="sensor.temperature",
</alrm>;n="TemperatureAlarms";d="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" />
]]></artwork>
</figure>
</section>
</section>
<section anchor="Acknowledgements" title="Acknowledgements">
<t>
</t>
</section>
<!-- Possibly a 'Contributors' section ... -->
<section anchor="IANA" title="IANA Considerations">
<t>This document requests no actions from IANA.</t>
</section>
<section anchor="Security" title="Security Considerations">
<t>This document has no known security implications.</t>
</section>
</middle>
<!-- *****BACK MATTER ***** -->
<back>
<!-- References split into informative and normative -->
<!-- There are 2 ways to insert reference entries from the citation libraries:
1. define an ENTITY at the top, and use "ampersand character"RFC2629; here (as shown)
2. simply use a PI "less than character"?rfc include="reference.RFC.2119.xml"?> here
(for I-Ds: include="reference.I-D.narten-iana-considerations-rfc2434bis.xml")
Both are cited textually in the same manner: by using xref elements.
If you use the PI option, xml2rfc will, by default, try to find included files in the same
directory as the including file. You can also define the XML_LIBRARY environment variable
with a value containing a set of directories to search. These can be either in the local
filing system or remote ones accessed by http (http://domain/dir/... ).-->
<references title="Normative References">
<reference anchor="wadl"
target="http://java.net/projects/wadl/sources/svn/content/trunk/www/wadl20090202.pdf">
<front>
<title>Web Application Description Language (WADL)</title>
<author fullname="Marc J. Hadley" initials="M.J.H" surname="Hadley">
<organization>Sun Microsystems Inc.</organization>
</author>
<date year="2009" />
</front>
</reference>
&I-D.ietf-core-link-format;
&I-D.ietf-core-coap;
&RFC5988;
&RFC2119;
<reference anchor="exi"
target="http://www.w3.org/TR/2011/PR-exi-20110120/">
<front>
<title>Efficient XML Interchange (EXI) Format 1.0</title>
<author>
<organization>W3C</organization>
</author>
<date year="2011" />
</front>
</reference>
</references>
<references title="Informative References">
<!-- Here we use entities that we defined at the beginning. -->
&RFC2616;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 14:30:41 |