Atom for ReST Data Representation

During the last weeks, I’ve been designing an architecture for a new application that’ll have to live in the cloud. Of course a ReSTful API comes as a natural fit. I must confess that I fell in love with ReST since, due to it’s inherent simplicity and naturality. And great libraries like Restlet or JAX-RS implementations exist to support development. Did I mention I’m using Java … ?

One of the major decisions to make when designing a ReST interface, would of course be data representation. Numerous options present themselves here, but after some digging and reading, the Atom Syndication Format combined with XML can be a universal data exchange envelope. especially when combined with some extensions like e.g. OpenSearch to support paging and searching. Atom’s extensive use of links with relation attributes, amongst others, make it a natural fit to ReST. Again, great libraries exist to ease the development of such Atom feeds, that even support the needed extendibility for the data envelope. These libraries even integrate nicely with the aforementioned technologies for ReST development.

The most renown use of Atom with XML for ReSTful service data representation would of course be the Google Data Protocol. However, when applying its philosophy to our own ReSTful services using various combinations of development libraries, implementation felt difficult every time, even awkward. At some point, I even considered re-implementing Atom libraries to support the needed extendibility of the generated feeds. Something smelt fishy!

Doing some more research, I came across articles from Atom authorities on how to (Ellias Torres) and how not to (James M. Snell, Rob Yates) extend Atom feeds. They also express their views on GData (Joe Gregorio, Clinton DeWitt).

I got my Aha Erlebnis this week when those guys pointed out where most extensions of Atom go wrong. There is a clear distinction between the data and the envelope. You can extend both, but for different reasons.

To support e.g. OpenSearch, you have to extend the envelope, because you want more intelligent data producing servers and data consuming clients. In developing ReST services, this type of extensions is more static as you will provide the extended envelope information with e.g. the search data, in every feed. So, e.g. you’ll super-class your micro-framework to support this extension once and for all.

On the other hand however, to transport your data, you have to extend you feeds at the data transport layer, which are the entries in Atom parlance. You’ll provide a representation for every entity you whish to ship, that you wrap in an Atom entry as its content. Hence, this wrapping will be a lot more dynamic in your system.

Applying above insights using different development libraries, the pieces of the puzzle fell into place as all libraries supported envisioned feed layouts very naturally. So I ended up choosing those libraries that supported my developments the best, which would of course be POJO style.