Mark Baker linked to this post which talks about how to access O’Reilly’s Safari Bookshelf using a REST API and has some example Java code. This post made me think about the relationship between the “ProcessMessage” approach that Jim and I have been advocating and REST. Are we that far apart? Well, I don’t think so.

In the example, some important piece of information is missing. How could the developer possible know that a) the returned document was XML (ok, check the appropriate HTTP header) and b) that the contents of the XML document had a root element “safari” and a child element “book”? Obviously they read some documentation, human-readable documentation.

What we are saying is that contracts and schema describe the same information in a machine-readable fashion (not semantics, but just syntax and patterns). So, I could actually validate the returned document, before going to the process of trying to read the data in it and reason about it. I could even use the contract to create programming abstractions (if I was afraid of processing XML).

Furthermore, why should an application like this be tied to HTTP? Isn’t the logic shared no matter what the transport protocol is? For example, someone may send the Safari catalogue to me via TCP/IP, email, or even fax it. That’s what Web Services is all about (at least the way I say them).

Finally, how did the application developer know how to construct the URL of the request? Again, some human-readable documentation from somewhere was used. Isn’t this the same as reading some documentation that describes a SOAP message exchange pattern? For example, Request…

<soap:Envelope>

<wsa:To>safari-address</wsa:To>

<wsa:MessageId>uuid:bla-bla-bla</wsa:MessageId>

<wsa:ReplyTo>me</wsa:ReplyTo>

<soap:Body>

<safari:bookshelf-request />

</soap:Body>

</soap:Envelope>

Reply…

<soap:Envelope>

<wsa:From>Safari</wsa:From>

<wsa:To>me</wsa:To>

<wsa:RelatesTo>uuid:bla-bla-bla</wsa:MessageId>

<soap:Body>

<safari:bookshelf>

<!- lots-of-books ->

</safari:bookshelf>

</soap:Body>

</soap:Envelope>

The above is transport-neutral, the contents of the message can be described in a schema language (e.g., XML Schema or RelaxNG), the message-exchange pattern (in this case request-response) can be described in an appropriate WS-specific vocabulary (e.g, WSDL), and tooling can be used to validate messages based on the metadata. Furthermore, I can think of more complex scenarios where I can send the request to the Safari bookshelf and request the results to be delivered to Jim (just by changing the ReplyTo element of the WS-Addressing information headers). But “wait” you say. How do you know that Jim would be prepared to accept a message like this? Well, Jim can describe this in his contract and also advertise policy information which will be restricting the originator of such messages to Safari. And all this information can be processed automatically by software.

I am really keen to hear the RESTferians take on this.