mark nottingham

WADLing towards Web Description

Wednesday, 18 May 2005

HTTP APIs

Marc Hadley has released WADL in the wild, and I’m intrigued; based on a first look, I’d say it’s the most promising Web (as opposed to Web Services) description language yet.

Why? First of all, it’s very resource-oriented; you can clearly and easily see the deliniation between different described resources. It encourages good practices, and supports generative URIs both in query strings and in path segments, which I think is crucial. It’s simple and easy to read.

Initial Feedback and Questions

That said, I can’t pass by an opportunity to give some feedback and ask some questions :) Many of my thoughts are based on experiences with my straw-man webdesc format (and its implementation in Python). I’m not attached to that particular format (there are far too many flying around already!), but I would like to see WADL waddle towards webdesc in a few ways.

1) First of all, the resources section is a great start, but as I understand the design, if you have a long list of resources, it’ll show up as a long, flat list of resource elements in WADL, like this:

<resources>
  <resource uri="http://www.example.com/">
  ...
  </resource>
  <resource uri="http://www.example.com/control-panel/">
  ...
  </resource>
  <resource uri="http://www.example.com/control-panel/button1">
  ...
  </resource>
  <resource uri="http://www.example.com/control-panel/button1">
  ...
  </resource>
</resources>

It seems to me that it would be much better to exploit the hierarchical nature of both URIs and XML to do something like this;

<resources>
  <resource uri="http://www.example.com">
    <resource uri="control-panel/">
      <resource uri="button1"/>
      <resource uri="button2"/>
    </resource>
  </resource>
</resources>

That way, you could refer into the tree of resources, relocate them easily, and so forth. Adding metadata that inherits down the tree would also be more naturally expressed this way.

2) I also wonder if it would be better to separate the mapping of URIs from the nature of the resources themselves; I know that WSDL has too much abstraction, but it seems like there’s a real advantage to having a map of URIs to resource types, like this;

<resources>
  <resource uri="http://www.example.com" type="#main">
    <resource uri="control-panel/" type="#control">
      <resource uri="button1" type="#button1" />
      <resource uri="button2" type="#button2" />
    </resource>
  </resource>
</resources>

so that you could, later in the document, have:

<resource id="main">
  <operation name="get">
    ....
  </operation>
</resource>

That way, you can reuse resource types separate from their mapping to a particular URI space; for example, if you want to deploy an application in multiple places.

I did it like this in webdesc;

<URIStructure base="http://www.example.com/" resource="#main">
    <pathSegment value="control-panel" resource="#control">
       <pathSegment value="button1" resource="#button1"/>
       <pathSegment value="button2" resource="#button2"/>
    </pathSegment>
</URIStructure>

This leads to a design where instead of using escape characters in the URI, you can just use the markup to indicate generative URIs, like this;

<URIStructure base="http://ldap.example.com/" resource="#ldapmain">
  <pathSegment value="people" resource="peopleContainer">
    <pathSegment type="#personName" resource="person"/>
    <!-- @type indicates that this pathSegment is generative, with that type -->
  </pathSegment>
</URIStructure>

3) Instead of the ref/name convention; why not use URIs to identify components? They’d allow you to refer to a type (or an operation, or a resource…) anywhere on the Web.

4) Also, WADL needs to more explicitly document extensibility, and also document what the scope of extension elements attached at particular points is. This is necessary so that you can say, for example, that you require HTTP authentication, or support compression, on an application-wide, per-resource, resource and children, per-operation, or per-representation basis.

Minor Nits

5) Does WADL have a namespace or a media type itself? It should (especially the latter, considering what it’s describing!).

6) How do you escape ‘{’ and ‘}’ characters, both of which are legal in URIs? (And, please don’t reference a language-specific convention in a language-neutral description format!)

7) I’m not crazy about ‘parameter,’ as it seems very RPC-ish. Not sure what else would be better, though.

8) With regard to ‘representation,’ keep in mind that some entity bodies are representational of that resource’s state; e.g., on a 4xx or 5xx status response, and with many POST requests. Some of the language should be adjusted to reflect that.

9) The language describing @element should be more explicit; I’d suggest “For XML-based representations, specifies the qualified name of the root element.”