Subject: [core] Comments on WADL Interface Description

From: Linyi Tian <[email-masked]>
Date: Wed, 30 Mar 2011 12:56:31 +0200

Hi, Matthieu and Zach

I asked several questions before regarding how to use Œ-d¹ attribute In Link
format. I am quite happy to see that Is explained In this new draft.

It Is a quite reasonable approach to describe the semantics and how to
Interact with the sensor. I have some general questions as follows:
1. WADL was not a standard so far. In W3C page, It says W3C has no plan to
work on It. Is there any other available technology can be used?
http://www.w3.org/Submission/2009/03/Comment

2. Do we need to care where to store the WADL file? Is there any
architecture impact?

3. Is it allowed to define the <Representation> and <Param> separately?
Secton 4.1
<resource_type id="sensor.temperature"> <method name="GET"
id="GetTemperature">
<request> <representation mediaType="text/plain" />
</request> </method>
</resource_type>

Section 4.2
<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>

4. If a representation for a param is ³application/xml², it will be left to
application to define the actual format. Is this correct?
<resource_type id="meter.power"> <method name="GET" id="GetPower">
<request> <representation mediaType="application/xml" />
</request> </method>
</resource_type>

Cheers,
Linyi

---

From: [email-masked]
Date: Wed, 30 Mar 2011 17:02:23 +0200

Hi Linyi,

Thank you for your comments. See my answers below.

>1. WADL was not a standard so far. In W3C page, It says W3C has no plan 
to work on It. Is there any other available technology can be used?
WSDL2 has now an HTTP binding to describe a RESTful interface. But the 
description is more complex than WADL.

>2. Do we need to care where to store the WADL file? Is there any 
architecture impact?
The CoAP clients are not supposed to fetch and parse the WADL file so 
there is no architecture impact.

>3. Is it allowed to define the <Representation> and <Param> separately? 
The examples in section 4.1 and 4.2 are supposed to be separate examples 
of the same concept. But for sure I should add a representation element to 
the example in section 4.2 instead of the implicit text/plain default 
value defined in CoAP.
Back to the question, a web link may contain more than one "if" ("d") 
attribute just like a WADL resource element may reference more than one 
resource_type element. According to section 2.8.2 of WADL it is allowed 
having 2 method definitions with the same method name for the same 
resource. Each definition is supposed to be a distinct variation. By 
extension I suppose several resource_type may also contain a definition 
for the same method name. Then it seems possible to merge the definitions 
for a resource. But I'm not sure whether the following example is a valid 
use case of "distinct variations" or not. So I would say don't do that and 
try to make a short and simple /well-known/core to save resources.
<resource_type id="sensor.temperature"> <method name="GET">
<response> <representation mediaType="text/plain" />
</response> </method>
</resource_type>

<resource_type id="unit.temperature"> <method name="GET"><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>

</tmp>;if="sensor.temperature";if="unit.temperature"

>4. If a representation for a param is “application/xml”, it will be left 
to application to define the actual format. Is this correct?
If you have a schema for your XML messages you can include it with a 
grammars element in your WADL description.
Then you can associate an element of your schema with a request or/and a 
response representation. Of course it is good practice to always include a 
schema for an xml representation although it is optional.
So the example could be improved like that:
<resource_type id="meter.power"> <method name="GET" id="GetPower">
<response> <representation mediaType="application/xml" 
element="em2:Power"/>
</response> </method>
</resource_type>

Regards,
Matthieu