I am happy to announce that the RESTful Web Services Cookbook is now available in stores.

Many thanks to Mark Nottingham, Eben Hewitt, Colin Jack, Stefan Tilkov, Norbert Lindenberg, Chris Westin, Dan Theurer, Shaunak Kashyap, Larry Cable, Alan Dean, Surya Suravarapu, Jim D’Ambrosia, Randolph Kahle, Dhananjay Nene and Brian Sletten for their valuable and critical feedback on this book.

If you are interested reviewing the book, please email me directly. The Yahoo! Developer Network may be interested in publishing a review.

• A source control system (Subversion) to manage the drafts from day 1
• DocBook as the preferred format – which let me use IntelliJ with DocBook DTDs attached for validation
• An auto-triggered build that generates a PDF version that looks more or less like the printed book
• An editor that provides the right dose of nudging on occasion
• Tool staff that are ready to help with tools and provide guidance on preferred use of DocBook
• Copy editors that remind how badly I write, and painstakingly provide corrections
• Production staff that follow through the process meticulously

We hiked up the Keechelus Ridge today. This is a moderately steep climb from the Price Creek Sno-Park. In just about three miles, this trail climbs over 1600 ft.

In Magic Signatures for Salmon, John Panzer describes a way to pass signed XML data without involving XML canonicalization (c14n). Anyone who has dealt with WS-Security specs knows that canonicalization can be fragile (back in my days at BEA, getting signatures to work on the WebLogic stack turned out to be hard due to bugs in the c14n implementation) and slow. John Panzer’s approach is quite simple, but it requires introducing an XML based envelope format.

In John’s approach, to send signed XML, the sender does the following.

• Serialize the XML using into UTF-8 encoded text.
• Generate a signature of the BASE64 encoded data.
• Use an XML envelope to send the BASE64 encoded data and the signature.

Before decoding BASE64 data, the receiver first verifies the signature of the BASE64 encoded data. If the signature matches, the receiver BASE64 decodes the data, and then parses the decoded text into XML.The most elegant part of this process is that canonicalization is not needed.

The envelope in his example looks like the following:

<me:env xmlns:me='http://salmon-protocol.org/ns/magic-env'>
  <me:data type='application/atom+xml' encoding='base64'>
PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4KPGVudHJ5IHhtbG5
zPSdodHRwOi8vd3d3LnczLm9yZy8yMDA1L0F0b20nPgogIDxpZD50YWc6ZXhhbXBsZ
S5jb20sMjAwOTpjbXQtMC40NDc3NTcxODwvaWQ-ICAKICA8YXV0aG9yPjxuYW1lPnRlc3RAZXhhbXBsZS5jb208L25hbWU-PHVyaT5hY2N0OmpwYW56ZXJAZ29vZ2xlLmNvbTwvdXJpPjwvYXV0aG9yPgogIDx0
aHI6aW4tcmVwbHktdG8geG1sbnM6dGhyPSdodHRwOi8vcHVybC5vcmcvc3luZGljYX
Rpb24vdGhyZWFkLzEuMCcKICAgICAgcmVmPSd0YWc6YmxvZ2dlci5jb20sMTk5OTp
ibG9nLTg5MzU5MTM3NDMxMzMxMjczNy5wb3N0LTM4NjE2NjMyNTg1Mzg4NTc5
NTQnPnRhZzpibG9nZ2VyLmNvbSwxOTk5OmJsb2ctODkzNTkxMzc0MzEzMzEyNzM
3LnBvc3QtMzg2MTY2MzI1ODUzODg1Nzk1NAogIDwvdGhyOmluLXJlcGx5LXRvPgog
IDxjb250ZW50PlNhbG1vbiBzd2ltIHVwc3RyZWFtITwvY29udGVudD4KICA8dGl0bGU-U2FsbW9uIHN3aW0gdXBzdHJlYW0hPC90aXRsZT4KICA8dXBkYXRlZD4yMDA5LTEyLT
E4VDIwOjA0OjAzWjwvdXBkYXRlZD4KPC9lbnRyeT4KICAgIA==</me:data>
  <me:alg>RSA-SHA1</me:alg>
  <me:sig>EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe
76up8w63i2fWHvLKJzeGLKfyHg8ZomQ==>/me:sig>
</me:env>

In this XML envelope, the me:data element contains BASE64 encoded data. The type attribute tells that the data is an Atom document. The me:sig element contains the signature.

But does sending a signature require an envelope? Here is an alternative that does not use an envelope.

Content-Encoding: base64
Content-Type: application/atom+xml;chatset=UTF-8
Authorization: salmon EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe76up8w63i2fWHvLKJzeGLKfyHg8ZomQ==

D94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4KPGVudHJ5IHhtbG5
zPSdodHRwOi8vd3d3LnczLm9yZy8yMDA1L0F0b20nPgogIDxpZD50YWc6ZXhhbXBsZ
S5jb20sMjAwOTpjbXQtMC40NDc3NTcxODwvaWQ-ICAKICA8YXV0aG9yPjxuYW1lPnRlc3RAZXhhbXBsZS5jb208L25hbWU-PHVyaT5hY2N0OmpwYW56ZXJAZ29vZ2xlLmNvbTwvdXJpPjwvYXV0aG9yPgogIDx0
aHI6aW4tcmVwbHktdG8geG1sbnM6dGhyPSdodHRwOi8vcHVybC5vcmcvc3luZGljYX
Rpb24vdGhyZWFkLzEuMCcKICAgICAgcmVmPSd0YWc6YmxvZ2dlci5jb20sMTk5OTp
ibG9nLTg5MzU5MTM3NDMxMzMxMjczNy5wb3N0LTM4NjE2NjMyNTg1Mzg4NTc5
NTQnPnRhZzpibG9nZ2VyLmNvbSwxOTk5OmJsb2ctODkzNTkxMzc0MzEzMzEyNzM
3LnBvc3QtMzg2MTY2MzI1ODUzODg1Nzk1NAogIDwvdGhyOmluLXJlcGx5LXRvPgog
IDxjb250ZW50PlNhbG1vbiBzd2ltIHVwc3RyZWFtITwvY29udGVudD4KICA8dGl0bGU-U2FsbW9uIHN3aW0gdXBzdHJlYW0hPC90aXRsZT4KICA8dXBkYXRlZD4yMDA5LTEyLT
E4VDIwOjA0OjAzWjwvdXBkYXRlZD4KPC9lbnRyeT4KICAgIA==

In this case, the Authorization header contains the signature, and the body of HTTP message contains base64 encoded bytes. I extended Content-Encoding to specify base64. I left out details like the signature method name, and the Authorization header can be extended to include such data, or such details can be specified as part of the authorization scheme (the way basic auth, digest auth, or OAuth do).

The magic envelope is HTTP (thanks to MIME).

In the ideal world, what we see is the current. In the distributed software world, what we see may be stale. We can't tell. Would not it be nice to specify a cache invalidation API such that the source of the change can notify everyone that it changed? That is what an OpenSocial 1.0 draft aims to do.

Containers MUST support the invalidation endpoint even if they do not perform any caching and MUST provide an entry for it in their XRDS. To invalidate content a developer’s backend notifies the container of the content it wishes to invalidate by making a 2-legged OAuth call to the Cache service with one or many keys to be invalidated. The consumer key in the 2-legged OAuth call is used by the container to identify the calling application.

This text is followed by an example.

POST /api/rest/cache/invalidate HTTP/1.1
Host: api.example.org
Authorization: hh5s93j4hdidpola
Content-Type: application/json

{
  "invalidationKeys" : [
      "http://www.myapp.com/gadgetspec.xml",
      "http://www.myapp.com/messagebundle.xml"
  ]
}

Excellent.

The due date (February 8, 2010) for WS-REST 2010 First International Workshop on RESTful Design is fast approaching. There is still time to submit papers for this workshop. Topics include:

• Applications of the REST architectural style to novel domains
• Design Patterns and Anti-Patterns for RESTful services
• RESTful service composition
• Inverted REST (REST for push events)
• Integration of Pub/Sub with REST
• Performance and QoS Evaluations of RESTful services
• REST compliant transaction models
• Mashups
• Frameworks and toolkits for RESTful service implementations
• Frameworks and toolkits for RESTful service consumption
• Modeling RESTful services
• Resource Design and Granularity
• Evolution of RESTful services
• Versioning and Extension of REST APIs
• HTTP extensions and replacements
• REST compliant protocols beyond HTTP
• Multi-Protocol REST (REST architectures across protocols)

This list is exhaustive. In particular, I would love to see contributions presenting on performance and QoS, tradeoffs, HTTP extensions and client/server side frameworks. See the call for papers for more details.

Most illustrations of the hypertext constraint (aka Hypermedia As The Engine of Application State) focus on managing application flows using links. In this approach, the server describes the flow using links, and clients, by interpreting link relations follow the links. While such an approach is useful for illustrative purposes, baking all the flow assumptions into hypermedia is easier said than done. Not every scenario could benefit from such application of the hypertext constraint. It could even be counter-productive in situations that need to leave the flow details to clients. Mashups are great examples.

I find it much more compelling to use hypermedia to encode certain implementation details such as concurrency control, security, and even transactions that can not and must not be leaked to clients . See RESTful Web Services Cookbook for details.

Here is an example that illustrates the title of this post.

<cart>
  <!-- some stuff here -->
  <link rel="http://ex.org/rel/abort" href="http://ex.org/cart/cancel;token=987654321"/>
  <link rel="http://ex.org/rel/add-more" href="http://ex.org/cart/add;token=987654321"/>
  <link rel="http://ex.org/rel/buy" href="http://ex.org/cart/buy;token=987654321"/>
</cart>

The URIs in this example are opaque to the client, but you can describe/document their semantics via link relations. These URIs let the client do things that are typically expected in a transactional application, such as aborting, saving, updating etc.

If you are searching for transaction support in HTTP and REST and are disappointed about not finding any support, you may not be looking at the right things. The hypertext is your transaction engine.

This is a short (under four miles) hike on a well groomed (but icy) trail to the upper fails in the Johnston Canyon on Dec 30, 2009. The falls are not completely frozen yet, but we were!

These are from one of the snowshoeing trips a few days ago near Lake Louise.