Restful Web Services book is the one to read these days. I enjoyed reading this book for a number of reasons. I've found this book challenging me and teaching me along the way.
I've decided to split a review into two parts. This blog entry is about what I liked about the book, what I found interesting. Next part will be about me trying to question some of the assumptions made in the book.
So here's what I liked about the book, in no particular order.
This book is written by people who believe in and more importantly, practise REST. This alone is a strong enough reason for anyone wishing to understand REST better to go and get the book.
I liked the style of the book, it is very moderate. Compared to some of the bloggers out there bashing WS-* to death, the authors showed how one needs to convince, not by using populist proclamations, but by rolling up the sleeves and teaching and showing how it all works. I found it encouraging me to think harder, trying to understand it better.
I thought I knew how POST was different from PUT. Oh, well :-) Now I do know ! Their description of why AmasonS3 service uses PUT to create new resources was both informative and practical.
The big plus of this book is that it presents a lot of the important information relevant to REST, HTTP, WEB which is spread across emailing archives, blogs and articles in a clear and concise way such that it's easy to understand and appreciate.
I liked a "My Web Service is my Web Site" idea. XHTML is given a lot of attention in this book and the effort to make XHTML a better language for the WEB deserves a lot of respect. Seeing how this format can be used such that the same response can be consumed by humans and machines was interesting. Microformats is a powerful idea all right.
I said it above but I found the coverage of big Web Services and contrasting them to RESTful services be moderate. Yes, authors believe REST does better overall but their conclusion didn't make me feel defensive. Obviously, the suggestion to try to refactor SOAP services such that they can respond to GETs is a good one which many people like.
Examples of how URIs should be formatted for different types of search requests were helpful. Things like when to use a comma, etc.
GET matters : one of the main messages I totally agree with. I personally believe GET matters most. I don't want to go into things like hypermedia of the application state (connectedness as authors describe it), late binding, etc. It's the ability to GET on the link is what really matters IMHO. GET and addressability.
Uniform interface : universal clients. Powerful. More comments though on it in the second part.
Great point about links, about how resources relate to each other, about driving the application from one state to the other one.
Suggestions to create separate resources to deal with asynchronous operations and to model the relationships are practical and useful.
Set of best practices on how to build RESTful web services is possibly the best one I've ever read.
There're other things which I may've missed.
Overall, I liked the book a lot. Useful, practical, insightful, and yes, challenging, if you're still, like myself, see some value in those embattled WS-* :-).
I have little doubt now one can rewrite pretty much every web service out there using a true 100% RESTful approach. I'm not convinced it is the right idea though in all cases where HTTP is involved. Or may be I just don't understand it and not seeing far enough. I'm open and I'm learning. I'll try to argue with a book :-) a bit in the second part.
Do I recommend the book ? Of course I do !!!
Thursday, September 20, 2007
REST and data sources
Dare Obasanjo has recently posted an interesting entry commenting on the formats Astoria will support.
What actually attracted my attention was the very first sentence saying :
"I’ve mentioned in previous posts that various folks at Microsoft have come to grips with the fact that RESTful Web services are the best way to expose data sources on the Web".
I personally believe this is exactly what RESTful Web Services are best at : at exposing data sources on the Web. Furthermore, I feel it's public data sources (those sources which are visible to more than one consumer) which can be exposed in a most efficient manner. It's when dealing with such public sources when most important RESTful properties such as linkability start paying off IMHO.
By no means I wish to imply that this is what Dare wanted to say. It is just what is said in that sentence fits perfectly well into my current view on what RESTful services are best suited for.
I'm still not convinced/certain that RESTful Web Services are the best fit for solving all types of problems in a web services space. I've heard some other people saying the same and I agree with them. I'll muse more about it later.
What actually attracted my attention was the very first sentence saying :
"I’ve mentioned in previous posts that various folks at Microsoft have come to grips with the fact that RESTful Web services are the best way to expose data sources on the Web".
I personally believe this is exactly what RESTful Web Services are best at : at exposing data sources on the Web. Furthermore, I feel it's public data sources (those sources which are visible to more than one consumer) which can be exposed in a most efficient manner. It's when dealing with such public sources when most important RESTful properties such as linkability start paying off IMHO.
By no means I wish to imply that this is what Dare wanted to say. It is just what is said in that sentence fits perfectly well into my current view on what RESTful services are best suited for.
I'm still not convinced/certain that RESTful Web Services are the best fit for solving all types of problems in a web services space. I've heard some other people saying the same and I agree with them. I'll muse more about it later.
ATOM and WS-Policy
You may want to ask, what can such specification as WS-Policy, with its WS- prefix :-), can do with Atom Publication Protocol (APP).
There're several things which I'd like to comment upon.
First thing is that the notion of Policy is by no means specific to the world where big (term borrowed from the RESTful Web Services book) WS-Services live.
Second, WS-Policy Framework and WS-Policy Attachment specifications are actually very neutral. They both use existing policy profiles like WS-SecurityPolicy in the samples but in itself nothing stops people using their own domain-specific policy expressions.
Framework specification is solid, the compromise between the complexity and simplicity has been achieved, one can build primitive and sophisticated policy expressions using a limited set of WS-Policy language operators.
Attachment specification is fairly simple, it defines a number of attachment mechanisms, and then proceeds and recommends how polices can be attached to existing WSDL contracts and UDDI registries.It also defines a mechanism to attach policies to arbitrary XML elements.
I've recently read an APP Feature Discover Draft. It's an interesting read. Here's one paragraph from the Introduction section :
"This document introduces an extension to the Atom Publishing Protocol (Atompub) service document [I-D.ietf-atompub-protocol] format that allows for the documentation and discovery of behaviors, functions or capabilities supported by an Atompub collection. Examples of such capabilities can include the preservation of certain kinds of content, support for draft entries, support for the scheduled publication of entries, use of a particular set of Atom format extensions, and so on."
APP is now considered be suitable for much more than just describing the process for working with feed collections. Typical RESTful service will deal with collections and its members.
Likewise, from the Introduction, it seems obvious to me that the goal which APP Feature Discover Draft is trying to achieve is the one WS-Policy is trying to achieve too except that WS-Policy is not trying to tackle the discovery problem in its current version.
It seems to me that WS-Policy might play the role of a bridge between the two worlds. APP is obviously a solid RESTful protocol. However it may be unrealistic to expect that everyone will use only APP in the future. There're other RESTful protocols around, such as the one dealing with Web3S documents, and there'll be a number of others too. What will unite all of these RESTful protocols is that the majority of them will support XML.
On the other hand, WS-Policy defines an attachment mechanisms which let WS-Policy expressions be attached to arbitrary XML documents. WS-Policy Attachment does not mandate what types of documents policies should be attached to, as opposed to the APP Feature Discover Draft which is linked to APP documents.
Here's an example from APP Feature Discover Draft, but using WS-Policy this time:
Using PolicyReference might not be correct as the policy engine may try to dereference it. I'm not sure one can express the capability with WS-Policy language the same short way as suggested in the APP Feature Discover Draft.
Perhaps something like wsp:PolicyAssertion can be introduced into the language to let policy authors say :
In meantime a better option might be :
This option may seem more verbose but a Policy operator provides for a grouping of policies and for more sophisticated policy combinations. Once we have more than one feature it can be handy to group them and this is where a Policy operator immediately pays off. Policy expressions can be applied to both service, collection and entry atom elements and to the custom content wrapped inside entries.
Atom clients can then do things like policy intersection by matching their own set of policy requirements with those associated with a given collection, entries, etc.
This analysis can be flawed in that it misses some important details. That said, it's difficult not to notice the obvious similarity between the goals APP Feature Discover Draft and WS-Policy are trying to achieve. It would be good to see a common language for expressing capabilities and requirements.
There're several things which I'd like to comment upon.
First thing is that the notion of Policy is by no means specific to the world where big (term borrowed from the RESTful Web Services book) WS-Services live.
Second, WS-Policy Framework and WS-Policy Attachment specifications are actually very neutral. They both use existing policy profiles like WS-SecurityPolicy in the samples but in itself nothing stops people using their own domain-specific policy expressions.
Framework specification is solid, the compromise between the complexity and simplicity has been achieved, one can build primitive and sophisticated policy expressions using a limited set of WS-Policy language operators.
Attachment specification is fairly simple, it defines a number of attachment mechanisms, and then proceeds and recommends how polices can be attached to existing WSDL contracts and UDDI registries.It also defines a mechanism to attach policies to arbitrary XML elements.
I've recently read an APP Feature Discover Draft. It's an interesting read. Here's one paragraph from the Introduction section :
"This document introduces an extension to the Atom Publishing Protocol (Atompub) service document [I-D.ietf-atompub-protocol] format that allows for the documentation and discovery of behaviors, functions or capabilities supported by an Atompub collection. Examples of such capabilities can include the preservation of certain kinds of content, support for draft entries, support for the scheduled publication of entries, use of a particular set of Atom format extensions, and so on."
APP is now considered be suitable for much more than just describing the process for working with feed collections. Typical RESTful service will deal with collections and its members.
Likewise, from the Introduction, it seems obvious to me that the goal which APP Feature Discover Draft is trying to achieve is the one WS-Policy is trying to achieve too except that WS-Policy is not trying to tackle the discovery problem in its current version.
It seems to me that WS-Policy might play the role of a bridge between the two worlds. APP is obviously a solid RESTful protocol. However it may be unrealistic to expect that everyone will use only APP in the future. There're other RESTful protocols around, such as the one dealing with Web3S documents, and there'll be a number of others too. What will unite all of these RESTful protocols is that the majority of them will support XML.
On the other hand, WS-Policy defines an attachment mechanisms which let WS-Policy expressions be attached to arbitrary XML documents. WS-Policy Attachment does not mandate what types of documents policies should be attached to, as opposed to the APP Feature Discover Draft which is linked to APP documents.
Here's an example from APP Feature Discover Draft, but using WS-Policy this time:
<service
xmlns='http://www.w3.org/2007/app'
xmlns:atom='http://www.w3.org/2005/Atom'
xmlns:wsp="http://www.w3.org/ns/ws-policy>
<workspace>
<atom:title>My Workspace</atom:title>
<collection href='...'>
<atom:title>My Atom Collection</atom:title>
<accept>application/atom+xml;type=entry</accept>
<wsp:policyreference uri='http://purl.org/atompub/features/1.0/supportsDraft'/>
</collection>
</workspace>
</service>
Using PolicyReference might not be correct as the policy engine may try to dereference it. I'm not sure one can express the capability with WS-Policy language the same short way as suggested in the APP Feature Discover Draft.
Perhaps something like wsp:PolicyAssertion can be introduced into the language to let policy authors say :
<wsp:policyassertion uri='http://purl.org/atompub/features/1.0/supportsDraft'/> In meantime a better option might be :
<wsp:policy>
<f:supportsdraft f='http://purl.org/atompub/features'/>
</wsp:policy>This option may seem more verbose but a Policy operator provides for a grouping of policies and for more sophisticated policy combinations. Once we have more than one feature it can be handy to group them and this is where a Policy operator immediately pays off. Policy expressions can be applied to both service, collection and entry atom elements and to the custom content wrapped inside entries.
Atom clients can then do things like policy intersection by matching their own set of policy requirements with those associated with a given collection, entries, etc.
This analysis can be flawed in that it misses some important details. That said, it's difficult not to notice the obvious similarity between the goals APP Feature Discover Draft and WS-Policy are trying to achieve. It would be good to see a common language for expressing capabilities and requirements.
Uniform XML Vocabularies on the Programmable Web
The question which I've been thinking about recently is what difference do uniform XML vocabularies (formats), as opposed to custom ones, make on the programmable web.
Specifically, while looking at Atom Syndication Format and Atom Publishing Protocol, I'm trying to answer the question :
What difference does it make to the consumer that the given collection resource's state is represented as an Atom feed with members being represented as this feed's entries as opposed to using a custom XML format to represent the state.
I think I start understanding better why people advocate using an Atom format to capture typical collection/member representations. One of the most cited reasons is that a lot of client tools understand the Atom format. This is an important enough reason for choosing a format which is widely supported. For ex, GData-based client tools can be both, say, Google Calendar clients and simple ATOM interpreters at the same time.
However, what I'm still not certain about, is what is the real audience of such uniform formats is.
Lets take one step back first. Many people asked : why do you use XML as opposed to that custom binary format ? One of the answers was that there were a lot of XML tools available on the market already. When writing client applications, you don't need to pick up a new parser every time, you just use the same XMLParser, the same favourite XML API, and get to the data of interest, feed them into JAXB generated classes or apply XPath expressions, and do something with it. It makes sense for all types of client applications, be they UI-based tools interfacing the humans or low-level applications passing the data along the chain for some further processing.
Now, if we have two different XML formats representing the same collection resource, then it's still XML. It's trivial to get to the data of interest and find the links to traverse the collection further, using XPath, WADL's cool feature to find the data of interest, etc. Using one format as opposed to the other one does not help much to understand associated semantics though
Lets say I write an application based on the uniform format like Atom, say, I write a Google Calendar application. If I get this application to consume an Atom collection representing the book library then the only thing I can do with this collection is to show it is to the human user, even though the Atom book collection may contains hints as to how to deal with a given book entry.
Specifically, while looking at Atom Syndication Format and Atom Publishing Protocol, I'm trying to answer the question :
What difference does it make to the consumer that the given collection resource's state is represented as an Atom feed with members being represented as this feed's entries as opposed to using a custom XML format to represent the state.
I think I start understanding better why people advocate using an Atom format to capture typical collection/member representations. One of the most cited reasons is that a lot of client tools understand the Atom format. This is an important enough reason for choosing a format which is widely supported. For ex, GData-based client tools can be both, say, Google Calendar clients and simple ATOM interpreters at the same time.
However, what I'm still not certain about, is what is the real audience of such uniform formats is.
Lets take one step back first. Many people asked : why do you use XML as opposed to that custom binary format ? One of the answers was that there were a lot of XML tools available on the market already. When writing client applications, you don't need to pick up a new parser every time, you just use the same XMLParser, the same favourite XML API, and get to the data of interest, feed them into JAXB generated classes or apply XPath expressions, and do something with it. It makes sense for all types of client applications, be they UI-based tools interfacing the humans or low-level applications passing the data along the chain for some further processing.
Lets say I write an application based on the uniform format like Atom, say, I write a Google Calendar application. If I get this application to consume an Atom collection representing the book library then the only thing I can do with this collection is to show it is to the human user, even though the Atom book collection may contains hints as to how to deal with a given book entry.
This makes me think that the uniformity of XML vocabularies in itself does not matter much. What matter more is the associated processing model.
For example, lets take SOAP. Understanding SOAP Envelope and Body does not help the application to understand semantics but it can let it become a SOAP node.
Atom Syndication Format describes how a feed may contain entries, but APP completes the picture by describing the processing model. This processing model is a sound RESTful model. But one can deal with collection resources RESTfully while defining custom XML formats too.
I think it all mostly matters to generic tools which can let a user to browse through the Atom collection, like a browser can let a user to browse through the collection resource whose state is represented as an XHTML page. Browser understands html links, an ATOM-enabled tool can understand atom:link entries and let user to browse through any ATOM-wrapped collection.
As I said, I'm not quite sure how other types of clients can benefit. If they need to handle books then dealing with books represented as atom entries won't help them to magically start dealing with fruits also represented as atom entries
I may've got it wrong but I'm still looking into it and I'll be interested to learn more about how uniform XML vocabularies can be applied. I've read this entry on the Microsoft Astoria blog recently, it was interesting to see the reasoning which led Pablo Castro to deciding in favour of supporting Atom.
Subscribe to:
Posts (Atom)
