Thursday, September 25, 2008

I've been asked a lot about use of SOAP in IETF standards. Most of the time, I think it's overkill and poor for interoperability, because it has a bunch of features that probably aren't needed, and if they are used, will not work unless everybody uses them the same way.

While using HTTP directly suffers from the same problem, at least the problem is not doubled by using SOAP over HTTP. And HTTP benefits from fantastic tool support and connectivity. So without further debate about whether HTTP itself is a bad or a good thing to use, here's how to use it in a standard.

  1. Define your objects, these will be HTTP resources. These are the objects people operate on. In Atom, these objects are entries, feeds and service documents. In CalDAV, objects are calendars and events. In a protocol for transferring karma between people, resources might represent individual karma accounts.
    If you can't think of objects but only of services, you may still be able to use HTTP POST to send requests to the service handler and get a response. I guess you're treating your service handler as a kind of object but it's only minimally RESTful to do this.

  2. Don't bother defining the URLs to resources. They'll be HTTP URLs of some kind. Let servers choose and clients discover.

  3. Define operations on your objects/resources. To create a new one, you should be using PUT (if the client can reasonably construct a new URL that the server will find acceptable) or POST if the server will pick a URL. To remove an object, use HTTP DELETE. To update an object by replacing its content, use PUT.
    Some commonoperations are defined in other HTTP extensions already. To update an object by making a change to it, use PATCH. To move or copy an object, use MOVE or COPY.

  4. Define how clients will find resources. E.g. Atom has service documents which locate feeds, and feed documents which locate blog entries. Because of Atom's strongly document-oriented approach, this means Atom uses GET requests for navigation and resource discover. CalDAV, by contrast, uses WebDAV collections for containers, therefore uses PROPFIND for the same purpose.
    You may find in this part of the exercise that you've invented new objects to help navigation and resource discovery work well. Reexamine your object model.

  5. If you need permissions, use the WebDAV ACL model if possible. Hold your nose if you need to. It's better than building one yourself. Leave permissions out entirely if you can wait a revision.

  6. Figure out if you've got any magic or use cases that aren't handled. E.g. CalDAV needed some magic to query calendars to find out "what events occur or reoccur this week". That wasn't solved with a RESTful PROPFIND request, so CalDAV defined some magic and used the REPORT method to carry the request for magic. Define your own new method for this one if you're dying to exert some creativity.

  7. Figure out the details. There are a fair amount. For example, define whether resources have fixed MIME types; whether caching is appropriate, whether ETags are required. It's probably a good exercise to walk through the section headings of the entire HTTP spec and say "Is this required to support, required not to use, or does it interact with our new protocol in some funny way."


Ok, I wrote this quickly to get it out and I'd love feedback. There are probably other recipes; this is the one I use. Exceptions exist. Void where prohibited.


orcmid said...

I like this as a quick brain dump and getting people thinking. I also like the "use the least complexity that can possibly work" notion that is latent in this approach.

So even if one might end up migrating into more complex WS- and SOAP waters, this is a heck of a good place to experiment and find out what works easily.

orcmid said...

In particular (afterthought) it is always great to find ways that don't require heavy server-side development (apart from content authoring) to get something rolling.

ale said...

I agree with the simplicity criteria expressed in the comments, and I like pure HTTP better than XML encumbered lengthy data. However, I beg to dissent.

Distributed development of SOAP based queries allows to quickly get past the syntax specification phase. By pulling in the XML environment, one has already defined lots of useful stuff. The resulting WSDL description is not short nor easily comprehensible, but it is machine readable, and agreeing on it suffices. Doesn't NETCONF work well?

Although I'm not a fan of "visual" developing environments, I'd be inclined to use SOAP for forwarding agreement handshakes, for one. When performance and terseness are less important than portability, ease and speed of development, availability of tools, and extensibility, I'd reckon that using SOAP can get the job done more quickly.

Because, as I said, I don't particularly like how SOAP tastes, I'd be happy to change my mind the day I'll learn how I can do the same thing without using it.

Blog Archive

Creative Commons License
This work is licensed under a Creative Commons Attribution 3.0 Unported License.