< Previous
Next >

[Comments] (6) Taxonomy of the Programmable Web! Part Deux: I know you're all for some reason anxious for the next report on my book progress. Well, in public it's all high-level philosophy but really the bulk of my day was spent chasing down Javascript and HTTP proxy hacks so I can finish "Ajax Applications as REST Clients".

However Sam and I did have a long IM conversation today, and cleared up a lot of taxonomy issues, as well as some of my misunderstandings about SOAP. I feel confident enough now to take another stab at my taxonomy of the programmable web. I got about halfway through before Ben came over to watch Battlestar Galactica, and that half is what I present to you tonight.

Again the disclaimer: though people will argue about these topics until the end of time, for purposes of this book we just need to get a coherent story about what it is we're cutting away as we zoom in on the programmable web to focus on the parts called "REST" and "ROA".

There are two major architectures on the programmable web. One is oriented around the passing of messages from place to place, and one is oriented around the manipulation of server-side objects called resources. We're (still tenatively) calling these the Message-Oriented and Resource-Oriented Architectures. Both architectures have real web applications and real web services to their credit.

These architectures can show up elsewhere than on the web, but we're not concerned with that. On the programmable web a service under either architecture uses the same underlying technologies: HTTP; a data format like XML, JSON, or form-encoded key-value pairs; and at least one URI.

Because they're built on HTTP, both architectures have a request cycle where the client asks the server to do something, and the server does it and sends a response. But we've found two questions which the MOA and the ROA answer differently:

  1. How is the request scoped? How does the client tell the server what part of the application it wants to operate on? Let's say the purpose of the request is to fetch some data. Why should the server send back data X instead of data Y?
  2. How does the client convey to the server what it wants the server to do? Why should the server send the requested data instead of modifying it somehow?

First a brief digression. When you send an HTTP request, you have two main options as to what to send in the entity-body. You can just send your data, or, if your data is an XML document, you can stick it in a box first. The name of the box is SOAP.

Just to avoid confusion: "SOAP" here is referring to the SOAP standard, not to the things people do with SOAP in the real world (that comes next). Sam says: "There isn't much to SOAP. It is three elements and a fault descriptor. Oh, that, and a world view." I'm just talking about the three elements and the fault descriptor. The worldview is the MOA.

Why would you stick your XML document in a box? Well, there are a variety of stickers that can be slapped onto the box without disturbing the contents. These stickers are the WS-* stack. That's the five-cent definition.

With that in mind, let's consider how the Resource-Oriented Architecture answers the two questions. A client for an ROA service scopes its request to a resource, by sending its request to a URI that identifies that resource. In an idealized ROA application there's one resource for every part of the application you might want to manipulate. Every resource has at least one URI, and you've got to send your request to some URI, so you might as well designate your resource by its URI. The URI goes in a special place in the HTTP request and can't be confused with anything else.

When conveying what it wants an ROA service to do to a resource, the client is restricted to a small and standardized list of methods. These methods are the famous HTTP GET, PUT, etc. Again, the HTTP method goes in a special place in the HTTP request and can't be confused with anything else.

If the client wants to convey an action that's not on that list, the problem is almost always that they've chosen the wrong resource. The service ought to expose some other resource for which the client's desired action translates naturally into one of the standard methods. The service might not actually expose this resource, but that just means the service can't do what the client wants. It's no different from the aggravation of a C library that's missing the function you need.

(There are edge cases I don't really understand, about overloading POST for atomic operations that span resources. I'm still trying to figure this part out. I think I may end up modelling this as a tiny MOA architecture inside the ROA.)

Now, depending on the service, when you need to send a document with your request, you might just send it as is, or you might stick it in a SOAP box first. The second possiblity, is, AFAIK, only theoretical. I don't know of any services I would describe as ROA where the client sticks its entity-bodies in a SOAP box before sending them.

This is partly for historical reasons. It's partly because it's simpler for the server to accept the entity-body as a document, instead of parsing it into a SOAP box covered in stickers, plus the "real" document. But it's mainly because HTTP already has stickers (HTTP headers). An HTTP request or response is already a box that can contain data and have stickers slapped on it.

HTTP stickers are more restricted in form than SOAP stickers, but they're good enough for most purposes. To the extent that ROA service programmers covet the features of WS-* stickers, they tend to devise ways of representing the same information in HTTP headers. Example: WS-Security's WSSE "ported" to the ROA as the X-WSSE header.

OK, enough about the ROA for a while. What about the MOA? And where do popular acronyms already in common usage fit in? Tune in tomorrow for the action-packed conclusion.

Filed under:


Posted by david at Tue Nov 07 2006 23:55

This is good stuff. The stickers discussion is actually quite useful, although providing specific examples (as you did w/ WSSE) is probably important.

Your "disclaimer" is a really good way IMHO to get past the terminology/nomenclature challenge. As you've stated it, I think everyone will be able to understand your intent and follow along, even if they don't choose to adopt your ROA/MOA terminology for themselves.

Are there some WS-* "stickers" that would require substantial effort to "port" to HTTP? The stickers conversation suggests that the two approaches (WS-* or ported equivalents for HTTP) are equally viable. But wouldn't the WS-* folks be right in saying that to port to HTTP, everyone would essentially be doing the port by themselves on their own? Perhaps this isn't a direction in which you intend to take the conversation. I mention it only because it's a direction in which I suspect the readers will go if you use the "stickers" metaphor.

Posted by Leonard at Wed Nov 08 2006 00:10

I'm still a newbie to WS-* but I think there are stickers such that porting them to HTTP would be more work than sticking a SOAP box inside your entity-body. My gut feeling is that any such sticker would probably be one that moved your whole app in the direction of the MOA, but I've got nothing to back that up.

If everyone ported their favorite stickers to HTTP on their own it'd be an uninteroperable mess. But I think ad hoc communities can form around specific stickers, like with WSSE. This is the sort of topic I'm hoping Sam can bring his insight to.

Posted by Mark Baker at Thu Nov 09 2006 00:37

Pretty good, but I've got a couple of issues. Perhaps when this is put in context they'll go away, but I'll mention them anyhow ...

When you say "The name of the box is SOAP", why is that? Why not, say, Atom

Also, you don't talk about SOAP's concept of "action" (the HTTP header, media type parameter, GED, or WS-A header) and how it interferes with the HTTP method. I think a lot of people - those familiar with SOAP - will be confused, or at least might miss your point because of this.

Similar to "action", there's also the wsa:To header which interferes with the HTTP Request-URI. WS-A isn't "core" though, like "action" is to SOAP, so I suppose there's less need to mention it.

I'll await the MOA stuff before deciding what I think of the MOA vs ROA comparison 8-)

Posted by Leonard at Thu Nov 09 2006 00:47

Atom would also work if you wanted to put an XML document in a box, but I didn't mention Atom in this context because people don't generally conflate Atom with other things. Whereas "SOAP" is often used as a shorthand for a style of web service design that combines SOAP with other technologies (esp. WSDL) in a particular architecture. What I'm trying to do is decompose all these terms into a relatively noncontroversial set of basis vectors, so that I can show how they're assembled into real-world architectures.

I shouldn't imply that SOAP is the only box format out there. But if all you want is a box then I'd say SOAP is simpler than Atom.

As you surmised, the next segment is where I mention SOAP features that conflict with HTTP features.

Posted by Mark Baker at Thu Nov 09 2006 09:16

I'm all for the "basis vector" idea, but I think you've got to be really careful about using overloaded terms as vectors. "SOAP" being a shorthand for a style (as you say), is a big issue. You need to be crystal clear that you mean (I hope) the spec, not the style, or else you'll have lost most of your audience who have a traditional WS background.

Honestly, I'm not sure how you make that distinction stick. Perhaps you could avoid mentioning any particular technology at this stage.

Posted by Leonard at Thu Nov 09 2006 09:33

This isn't organized the same way as it will be in the book, so I think I can do that. I also added a clarification paragraph to this entry.


Unless otherwise noted, all content licensed by Leonard Richardson
under a Creative Commons License.