It’s just data

Unification: REST, SOAP, RSS, Blogger

Joe GregorioThere is a lot of discussion on the proposed Blogger API Version 2.0 and Ben brings up some very good points. This gives me a chance to trumpet REST in general and RESTLog specifically in how they solve these problems.

Seed planting time.

What if allowed for the posibility that <item> elements it receives using an HTTP PUT may be enclosed in Envelope and Body elements, as described here.  All I am asking is that these be ignored... the one exception is if some XML element contains a mustUnderstand attribute with a value of "1", then you return an appropriate SOAPFault.

I'm not suggesting that such an envelope be required, or that any other changes be made to the API.  Merely that it be tolerated if it were present.

I can donate the Python server code for generating a SOAPFault message.

Just to make sure I understand, allow an optional SOAP envelope any time the 'item' is used in the content of a PUT or POST. Do not wrap the results from GETs in a SOAP envelope?

If that is the case then that is a reasonable request and I would gladly accept the donated code.

What I don't understand is why? This isn't a form of interaction supported by a traditional SOAP stack. I will admit that I've been a slacker and haven't looked at the SOAP 1.2 spec or the latest WSDL spec. Is this kind of interaction now allowed?

Posted by joe at

My suggestion for the moment is POST only. Wrapping the results of a GET with a SOAP Envelope is a SOAP 1.2 kinda thing - for now, I am focusing on something that would work with existing SOAP stacks.

Sending arbitrary XML inside a SOAP envelope and receiving like responses is exactly what SOAP 1.1/WSDL 1.1 document literal is all about. I could slap together a WSDL in minutes and you could generate C# proxies with your existing copy of WSDL.EXE, and VS.NET users could get intellisense...

I could do similar things with the existing Axis code. Or PocketSOAP. Or...

Posted by Sam Ruby at

Aaah, that's what document literal is for!
But you are still restricted to POST because of SOAP, correct?

Which means that in the case of the RESTLog API you could create new items but not be able to edit them.

Regardless I'd like to implement this and try out the proxies VS.NET comes up with.

Posted by joe at

SOAP 1.1 is at best ambiguous when it comes to methods other than POST. SOAP 1.2 clarifies this considerably.

It seems to me to be perfectly in accordance to the principles of REST to permit the use of POST for requests intended to apply changes to a resource.

Posted by Sam Ruby at

I am just looking at it from an interpretation of HTTP, which is one (the only?) system that follows the REST architecture. I think the use of PUT vs POST in RESTLog is correct when viewed against the HTTP specification:

In RESTLog to create a new news item, the 'item' fragment is POSTed to the base URL RESTLog.cgi. To edit a story you do a GET on RESTLog.cgi/id and then PUT the edited 'item' back to RESTLog.cgi/id. just writes over the old file with the new contents. So PUT is used here because it is not changing or annotating a resource but replacing it.

POSTing to RESTLog.cgi/id could be for things that are extending or annotating the 'item' such as TrackBack, annotations, or comments via a web form.

I'll have to finally read those SOAP 1.2 specs to see what they say about PUT and other verbs.

Posted by joe


If you want to get technical, on a system that supports POSTing of comments, a PUT to the same URI should be considered as providing a modified version of the entire resource - comments and all.

A concrete example to illustrate a point: POST on a WIKI replaces the visual portion but not the history of the resource.

There is nothing wrong with a resource supporting both POST and PUT.

Posted by Sam Ruby at

I agree that there is nothing wrong with a resource that supports both PUT and POST.

"a PUT to the same URI should be considered as providing a modified version of the entire resource - comments and all."

But that is exactly how I would implement a commenting system. If you did a GET on the item it would return an 'item' fragment with all the comment and trackback info attached. This would let you edit an item including removing comments or deleting trackbacks.

With respect to the WIKI example, is the history retrieved from the same exact URL or is it viewed through a different URL?

Posted by joe at

IMHO, a comment POST should just contain the comment. That's how this comment system is implemented, anyway. Having multiple clients doing complete PUTs results in what realtime programmers call scoreboarding - i.e., lost data.

Technically MoinMoin, for example, does provide info at a different URL than the content. This url is formed by appending the string "?action=info" to the end of the resource for which you are interested.

Posted by Sam Ruby at

Ok, I think we have a misunderstanding.
The POST for adding a comment is how this and all comment systems should work. I agree. When I talked about PUTing it was through the admin interface. The client side app used by the weblog author to edit items, but GETing and PUTing XML 'item' fragments. Now bundling all the comments, trackback and the item content may not be the *best* way to handle it, though it will be my first pass implementation. An alternative approach would be to create seperate URLs that contain just the comments, just the trackback, etc. Then do GET/PUT on those URLs to edit them.

As to scoreboarding, HTTP has a way to prevent that:

Looking at the MoinMoin interface
PUTing a new representation shouldn't erase the history since the history
and the content are located at different URLs.

Posted by joe


[...this really isn't the discussion I wanted to have...]

A strict reading of section 9.6 would indicate that a PUT "MUST NOT attempt to apply the request to some other resource.", which I would interpret to mean that a PUT not only wouldn't erase the history stored at another resource, it wouldn't affect the history.

But truth be told, real world implementations of HTTP there is a lot of "wiggle room", including for examples the uses of HTTP GET to return hit counters, and POST to do everything from queries to airline reservations.

My intent was not to say that there is anything wrong with supporting PUT, but that there might be incremental additional value for also supporting POST in specific cases - none of which (IMHO) violates your desire for a RESTful interface.

Posted by Sam Ruby at

So much for seed planting :) Sorry, I can be dense at times, but I don't quite get the point. It seems pretty obvious to me that you could put SOAP, XM-RPC and RESTLog interfaces on the same CMS engine.

Sure, if I switch all my PUTs to POSTs and wrap all my content in SOAP headers then that is obviously SOAP, though given that new URLs are created all the time I would have to generate a WSDL file on the fly... ouch!

Maybe my difficulty comes from my perspective on RESTLog. With RESTLog I am not trying to build a CMS and happened to decide to use a RESTian interface. I decided up front to use the REST architecture exclusively to gain experience, learn the pitfalls and explore the possibilities. I happened to build a CMS first, so I had to dog-food my own ideas daily. The next project may be a micropayment architecture or a distributed eBay. No matther which project I do it will be done using REST exclusively.

I have learned a lot from this discussion. For example my thinking on comments, Trackback and history are a lot clearer now. Thanks.

Posted by joe at

Have I made one single suggestion that is contrary to an completely RESTful architecture? My suggestions were not of the nature of bolting another interface on the side, but rather one of being both architecturally correct and widely inclusive.

Just yesterday, you were saying "This isn't a form of interaction supported by a traditional SOAP stack.". With a minimum of effort, you could produce the shining example of the "proper" way to do web services.

Also, there are no need to generate WSDLs. With the stubs that WSDL.EXE generates, a single assignment statement is all it takes to modify the target location.

Posted by Sam Ruby at

"Have I made one single suggestion that is contrary to an completely RESTful architecture?"

Well, using POST where PUT should be used, but I am sure we disagree on that :)

"Just yesterday, you were saying..."

Yes, I wasn't thinking of document literal. I have never used SOAP that way. Now I know.

I'm still game. I can add the code to handle POSTs and ignore the SOAP envelope if you want to write the WSDL.

Posted by joe at

I'm really not sure I like the precedent you're suggesting here, for a lot of reasons.

The first is just that most of the markup that SOAP provides has always struck me as basically dreck. I don't appreciate envelopes that are stuck directly to the messages inside, though I do open them when they appear. (In the real world, they often contain checks or other financial news.)

The second is that "include extra junk in other namespaces that you can just ignore" is an approach that is both far from universal and also complicating. There's nothing in the namespaces spec, for instance, that proposes such a thing, and the extra overhead in bits, processing, and general readability is unfortunately genuine.

I guess that I'd much prefer that formats which are about the message define the message, and IF people using SOAP want to deal with that message format, it's then THEIR problem, not a problem that affect people who aren't using SOAP.

It feels to me like you're asking people to annotate elements with xsi:type so that type-aware processors can process them more easily, even when most people aren't going to bother.

Posted by Simon St.Laurent at

And I should clarify that I don't think making the extra SOAP (or xsi:type) information optional helps the situation anyway. Saying "you don't have to use it" only reduces one small facet of costs.

Posted by Simon St.Laurent at

Joe - just to reiterate, with SOAP 1.2, support for PUT becomes more clear in the spec; meanwhile, from a REST perspective, this is a valid usage of POST.

Simon - with all due respect, I think you are talking about RPC encoding. I am asking for Joe to literally put his document intact into an envelope with no other changes.

I've documented my thoughts on extensible interfaces elsewhere: Example: Expect More and Coping with Change. I also recommend Dare's W3C XML Schema Design Patterns: Dealing With Change

Posted by Sam Ruby at

No, I'm not talking about RPC encoding.

I'm claiming that the SOAP envelope information SHOULD NOT be permitted in the message format for cases where SOAP is not being used for the transfer.

RPC or no RPC, the SOAP envelope is purely added dreck in this case. If SOAP developers want to use Joe's documents, they can and should do so, but asking Joe to put the SOAP info into the message vocabulary (even just to be ignored) is a major mistake, a sign that SOAP is invasive even when RPC encoding is not involved.

Posted by Simon St.Laurent at

Sam - I do have a question on the extent of this experiment. In RESTLog GET is used to retrieve the representation before editing and DELETE is used to remove items. How do you think these cases should be handled?

I agree with Simon that the use of envelopes is a long term problem. For example what if XForms required it's own wrapper around the instance data? (It doesn't)
Then I would have to serve up three forms of an 'item', one plain, one wrapped in a SOAP envelope, and another wrapped in an XForms envelope.

Posted by joe


Re: "SOAP is not being used for the transfer"... the transfer protocol in this case is HTTP. I'm not suggesting that that be changed.

At the beginning of this thread, I made refererence to planting a seed. It is my experience that wandering into a topic area which attracts the types of people who tend to listen with their mouths open, that the best course of action is to focus on small concrete proposals which do not require participants to compromise the positions that they have taken in the past and produce clear and tangible results.

In this case, my intent is to show Joe a few tricks that WSDL.EXE can do. You are certainly welcome to listen in...

Posted by Sam Ruby at

Unfortunately, I don't believe that what you're proposing qualifies as a "small concrete proposal." It's a substantial change to the overall structure (and nature) of the content, with implications that go beyond a few concrete tags.

Sometimes "listening with your mouth open" is a very good idea, if only so you can spit out some of the seeds that other people mysteriously think are small and harmless.

If you'd prefer that I merely listen in and not comment, that's fine - it is, of course, your blog.

Posted by Simon St.Laurent at

Green Eggs and Ham

Renowned RESTian and self proclaimed tech-curmudgeon Mark Baker says I think good thoughts when I talk about converging REST, SOAP, RSS, and Blogger. Meanwhile, the monastic Mr. St. Laurent prefers to spit out the seeds I'm trying to plant. First he... [more]

Trackback from Sam Ruby


Pingback from Sam Ruby: Can.Worms.Open()


More RESTful API Discussions.

Joe Gregorio and Sam Ruby have been busy discussing the use of SOAP and WSDL in RESTful APIs like Joe's RESTLog. ... [more]

Trackback from tima thinking outloud.


Verbs Suck

Joe Gregorio: XForms doesn't support the DELETE verb. I find this very amusing. Forget SOAP. Forget ReST. Consider the following flow. I POST an email address to a URL. An SMTP message comes to that address. In the body of that message is a URL. ...

Pingback from Sam Ruby: Verbs Suck


A SOAP/RSS is simpler then you may think.

In another thread to my O'Reilly post on Weblogs, Web services and the future, an anonymous poster raises the notion of using SOAP instead of XML-RPC. While other disagree I think this notion definite has merit as part of a solution when combined... [more]

Trackback from tima thinking outloud.


To make things even more interesting, there is now another alternative for RPC calls, in the spirit of XML-RPC: XINS.

Complete announcement (from
"After 2 years of development, there is now a BSD-licensed web services technology that competes with the allegedly overcomplex Microsoft SOAP technology: XINS. XINS is heavily based on Java and XML. Main design goals include simplicity, scalability and testability. Features include transaction logging, log documentation, and automatic generation of HTML docs, test forms, client-side and server-side code. A comprehensive user guide is available."


Posted by Ernst de Haan at

Sam Ruby: Unification: REST, SOAP, RSS, Blogger

mentions soap literals...

Excerpt from at

Add your comment