Preview API
Use the comment API with one additional SOAP header:
<wfw:preview soap:mustUnderstand="1"/>
Joe, there are a number of downsides to doing it that way, which I touched on yesterday. In particular, what would your implementation of the comment API do with such a request (presuming the experimental SOAP support is enabled)? Would it simply Expect More?
In any case, there's nothing like a concrete implementation to flush out the issues, so let me go ahead and ask: do you have any issues with this?
Posted by Sam Ruby atThe experimental SOAP support isn't in place anymore, that is, it no longer gives a SOAP fault or a response wrapped in an envelope if it receives a message in a SOAP envelope.
This does leave me in a bit of a quandary, as I am using XmlToDict to parse the incoming XML. Which means if you POST that message that I will take it as a comment. Probably not what you would expect.
Posted by joe atI think this is a good example of the use of SOAP. I'm curious how this would be done with REST.
I also like the use of hyperlinks in the XML code very much.
I was only wondering if the response to the client example should have been "the body element does not validate", instead of silently adding a div. (but I see you just removed the bold element, so now it does validate)
Posted by Sjoerd Visscher atJoe: it is a shame that you have removed the experimental SOAP support. In particular, I have found the stack tracebacks in faults very helpful in debugging.
My server implementation maps XML not only to dictionaries, but also to classes. Very handy.
I do believe that there is a need for mustUnderstand semantics in evolveable APIs. Do you have an alternate suggestion?
Posted by Sam Ruby atSjoerd: I will assert that this is fully in compliance with the principles of REST.
As to the validation: I am liberal in what I consume and conservative in what I produce.
Posted by Sam Ruby atThus my use of the word 'quandary', as I don't have an alternate suggestion right now.
Posted by joe at
Being liberal in what you consume is great, but it prevents the opportunity to educate. How about adding a warning to the header of the reply?
I agree that this is in compliance with the principles of REST. But not with the example at wfw. I was wondering if there is a restful solution without wrapping the data.
Posted by Sjoerd Visscher atJoe: Cool. Think about it a bit. I'll still be here.
My thesis (by virtue of the various essays on the left) has been that REST has value and SOAP has value. They both can be productively applied.
What I have found is that rational people too often assume that given enough thought they can design perfect interfaces to begin with. Failing that, they can always design in enough extensibility. And that everything else is such a remote edge case that it can be trivially dismissed.
And many of vocal REST advocates have dismissed headers and faults for just this reason. My experience is that arguing on theoretical grounds never works. Nor does working with fabricated examples help. It takes actually working through a real world example and then changing the requirements in a very reasonable and, in retrospect, predictable way to drive home the point.
Does it make sense to have a comment API without the possibility of supporting a preview function? How about a metaWeblogAPI without categories? These are very much real examples.
Sorry to take you down the primrose path buddy. Next RTP bloggers lunch is on me.
Posted by Sam Ruby atSjoerd: your web log is strict HTML 4.01. I gather based on your comments here that this means that it isn't as RESTful as it could be. Could you do me a favor and remove the <html>, <head>, and <body> wrapper elements so that I can get a full appreciation of what you would consider to be more RESTful solution?
Posted by Sam Ruby at
Sam, I'll use whatever I think works best. For now I'm totally on your side.
But as you say, many REST advocates dismiss headers, and I remain interested in how they would do this.
Posted by Sjoerd Visscher atSam,
Here is a little bit of my thinking. That 'wfw:preview' looks a lot like a verb. In this case you are using that verb to multiplex what the URL does. If you POST an 'item' it creates a comment, but with this additional 'verb' it gives a preview of the comment that would be created.
After reading your Cohesion essay, I took to the idea of just two verbs. That is, on the web there is just GET and POST. GET modifies the state of the client while leaving the servers state unchanged. POST changes the state of the server while leaving the client state alone. It is a nice clean abstraction that new layers can be built upon and ties in nicely with the Neurotransmitters essay. That is, "The idea of messages being entirely self contained and routed across great distances to be interpreted by the recipient is the recurring theme that I want to highlight here." Here I thought the target URI is the one responsible for the interpreting.
My first comment in this thread was just pointing out that I originally mis-understood your proposal. Now that I understand it some more I think this functionality needs a different URI.
On the other hand, let me
completely contradict myself and
suggest you could add
<wfw:commit>no</wfw:commit>
or
<wfw:commit>yes</wfw:commit>
to the 'item' being POST'ed. Right now the CommentAPI only specifies that i returns the HTTP return code. Doing the above 'wfw:commit' would require the CommentAPI to return the 'item' in it's updated form, or, return a Location: header with URL of the updated 'item' preview.
I particularly like this second idea since I can just re-use the same 'wfw:commit' element on RESTLog to enable previewing articles without posting them to the front page.
Posted by joe atOK, we're getting closer to my dream:
http://www.intertwingly.net/blog/1303.html#c1049122585
Posted by Mark at<wfw:preview> does look a lot like a verb. In fact, I'd call it an adverb. We can quibble over semantics and argue that Topology was too restrictive (my point was to draw attention to message exchange patterns instead of verbs), and I will concede much of this. I would only suggest that from REST perspective, this does not represent a separate resource.
I would suggest that a more precise definition than adverb: in this case it is metadata targeted at an actor. The actor being the commentAPI application itself.
The desired goal is to loose coupling and to create data which outlives applications. You are now talking about modifying two applications in a coordinated manner.
If you like, I can repeat this process. Furthermore, I'd like to see this data be used for more than comments and posting blog entries: notification, aggregation, pinging, archiving, etc. The coordination costs goes up with each application.
One way to limit the impact on applications is to judiciously pick the defaults to that the new elements are optional. The problem is that clients can never reliably know when they can send such elements. So they won't.
To make this work, there needs to be a mustUnderstand attribute, and all an application needs to know is that it is to reject messages which contain such attributes on elements which it doesn't understand. Now you can safely evolve interfaces and those that can process the requests will, and those that can't process the requests won't.
So, if you look to solve the general problem in a general way, and are predisposed to express metadata in a well formed way, what is the simplest layout that meets these requirements? I think I know the answer.
Furthermore, if you take a look at soap.py, you will find that the implementation costs are minimal.
By the way, there are no more rabbits in this hat. Nothing more will crawl out of any rocks. Optionally handing SOAP in the manner I have outlined will not only cost little, but it will increase the number of potential clients, and will provide considerable insurance against requirements that will inevitably surface over time.
You do not like them.
So you say.
Try them! Try them!
And you may.
Try them and you may, I say.
preview API
Sam has updated his comment API to support a preview mode. Whilst I normally agree with what Sam writes regarding Web Services, this one just doesn't sit right with me, it smells very RPCish going against Sams own messaging message. It seems to me,...Excerpt from Simon Fell at
Interesting. I initially mis-read this.
What I thought you were proposing was:
<wfw:preview>http://bitworking.org/news/comments/52?prev</wfw:preview>
could be placed in the RSS file, just like:
<wfw:comments>http://bitworking.org/news/comments/52</wfw:comments>
Posted by joe at