Joe
Gregorio: There is a lot ofdiscussionon the proposed Blogger API Version 2.0 and
Benbrings 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 RESTLogImpl.py 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?
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...
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. RESTLogImpl.py 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.
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.
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?
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.
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.
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.
[...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.
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.
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.
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.
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.
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'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.
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) http://www.w3.org/TR/2002/CR-xforms-20021112/slice2.html#concepts-xml-instance-data 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.
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...
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.
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]
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.
at
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. ...
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.
at
To make things even more interesting, there is now another alternative for RPC calls, in the spirit of XML-RPC: XINS.
Complete announcement (from OSnews.com):
"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."