mark nottingham

Using WebDAV as a Description Format for REST

Tuesday, 27 April 2004

HTTP APIs

In the past, I’ve talked about reusing WSDL as a format for describing Web resources, as well as coming up with a bespoke format.

One path that I’ve overlooked so far is reusing WebDAV to describe Web resources. The WebDAV protocol defines and allows you to describe the properties of a Web resource; e.g., the last-modified time is such a property, and so is the fact that it requires authentication.

WebDAV also defines a way to get a representation of the properties of one or more resources, with the PROPFIND method. If you send a PROPFIND to a resource along with a Depth HTTP header, you can get back a “multistatus” response, which describes the properties of a number of related resources, in an extensible XML format.

With only a small amount of imagination, WebDAV’s multistatus format could be viewed as a Web resource description format. However, there are some limitations which, in my mind, make it unsuitable. Let’s dig a bit deeper.

If we go back to our address book example, it might look something like this through WebDAV goggles;

<D:multistatus xmlns:D="DAV:">
     <D:response>
          <D:href>http://www.example.com/people/Bob</D:href>
          <D:propstat>
               <D:prop>
                    <D:creationdate>2004-04-08T17:42:21-08:00</D:creationdate>
                    <D:displayname>An entry in the address book.</D:displayname>
                    <D:getcontenttype>text/html</D:getcontenttype>
               </D:prop>
               <D:status>HTTP/1.1 200 OK</D:status>
          </D:propstat>
     </D:response>
     <D:response>
          <D:href>http://www.example.com/personFinder</D:href>
          <D:propstat>
              <D:prop>
                    <D:creationdate>2004-01-12T13:22:09-08:00</D:creationdate>
                    <D:displayname>Finds entries in the address book.</D:displayname>
                    <D:getcontenttype>text/html</D:getcontenttype>
                    <x:queryArgs xmlns:x="..." xmlns:xsd="...">
                        <x:arg name="name" type="xsd:string"/>
                    </x:queryArgs>
               </D:prop>
               <D:status>HTTP/1.1 200 OK</D:status>
          </D:propstat>
     </D:response>
</D:multistatus>

Using an existing format would be a great boon, but I see a few potential problems here.

First of all, there’s no means of typing resources; i.e., you can’t say that all Foo resources require authentication, allow GET and POST, and produce HTML; you have to enumerate each of them, and repeat the appropriate metadata for each one. I suppose one could describe a synthetic resource (e.g., by making D:href point to a URI that identifies the type, rather than a specific instance of it). This seems a bit of a hack, though, considering the semantics of multistatus.

Another is content negotiation; as far as I can tell, WebDAV doesn’t support describing different representations of the same resource. Also, I can’t see any way to accommodate generative resource names in this format, without breaking a lot of existing WebDAV implementations. Altogether, these are pretty limiting problems; while you could probably come up with workarounds, it wouldn’t be a very easy format to edit or visualise, at least without the help of tools.

Another way of seeing these problems is in terms of abstraction; where WSDL went too far, this format doesn’t go far enough — not that this is WebDAV’s fault, as I’m trying to do something that it’s not really designed for. I don’t think we can just pick up this format and use it to document the interface provided by Web resources.

How About Reusing Properties?

Still, the property model is compelling; there are a large number of them defined (I’ve taken a first pass at a collection of properties defined in RFC and I-Ds, as alas, there is no registry yet), and they cover a pretty useful swath of functionality.

Additionally, if your description format is compatible with them, WebDAV becomes much easier, and that’s a good thing; it can readily be seen as an alternate UI for resources, one that makes a lot more sense than a browser in some use cases. In the other direction, WebDAV could be used as an update and synchronisation protocol for resource descriptions, if desired.

Unfortunately, another problem pops up; because WebDAV properties have the granularity of an entire resource, it becomes difficult to use them to describe things on a finer grain.

For example, this is a WebDAV property that describes the access control requirements of a resource;

<d:acl xmlns:d="DAV:">
    <d:ace>
        <d:principal>
            <d:href>http://www.example.com/acl/groups/maintainers</d:href>
        </d:principal>
        <d:grant>
            <d:privilege><d:write /></d:privilege>
        </d:grant>
    </d:ace>
    <d:ace>
        <d:principal><d:all /></d:principal>
        <d:grant>
            <d:privilege><d:read /></d:privilege>
        </d:grant>
    </d:ace>
</d:acl>

As you can see, it gives rights like “read” and “write”. In a description of a Web interface, the most natural level to talk about these things is at that of methods, not resources; e.g., “GET allows anyone, but PUT allows maintainers.” While there is a mapping from WebDAV privileges to the appropriate HTTP methods, it’s not a direct one, and it isn’t clear how you’d handle things like POST (in fact, the current draft of WebDAV ACL doesn’t talk about POST at all).

Conclusions to Date

Make no mistake, WebDAV is a great protocol, and I’m excited about the possibilities for its use. However, the multistatus structure really isn’t suitable for the description of Web interfaces; although it’s capable of doing so in limited cases, it doesn’t encourage good practices in their design.

Likewise, WebDAV properties are ripe for being leveraged, except that they suffer from a fixed scope — that of the resource. As Jeff Mogul’s paper [pdf] points out, there are a lot of different levels where it’s interesting to talk about HTTP metadata.

In many ways, this is no different than the trade-offs inherent in leveraging WSDL; while it would be functional, its questionable whether reuse brings enough benefits to justify fitting a round peg into a square hole (or vice versa). Neither WebDAV multistatus nor WSDL was designed to describe stateful resources that have multiple representations and a constrained number of methods bound to a single protocol, HTTP. Neither, when used in this way, promotes good resource modelling (an art for which there isn’t nearly enough guidance available).

Of course, any description format’s mechanisms (like acls, redirect and so forth) will need to define a mapping to WebDAV properties to ensure that WebDAV is enabled. The trick will be making that mapping fairly direct and easy.

The net is that, so far, I think we need a clean-room format that’s designed to promote good practice. Before I go much further down that path, however, I need to explore one or two more options for reusing existing formats.