The Web 2.0 world seems to hate XML. And who can blame them, when JSON maps much more neatly onto the data structures they're used to dealing with in their everyday programming languages?
It is a shame, however, that this is leading to the return of the previous generation's big API design anti-pattern: public APIs that are just straight dumps of internal data structures. This means that everyone's API is different, and you need to rewrite everything from scratch for each provider. Worse still, representations and protocols and access patterns are all inextricably tied together, making it hard to reuse good ideas from one provider's API in another.
In a world that's rejected XML, it's getting pretty hard to push AtomPub as a standard API for submitting and managing web content. Some providers are paying lipservice to it by supporting Atom as a representation format, but AtomPub is not really about Atom... it's about using HTTP principles as your API model, which of course is what we today call the REST archetectural style.
I personally thing AtomPub has a pretty nice API model. It defines two simple concepts: a "collection" and an "item". It also defines a few different operations you can peform: you can add a new item to a collection, you can retrieve items from a collection, you can retrieve individual items and you can update and delete individual items. If you ignore the Atom Syndication Format part the basic model is a nice basis on which you can build almost any higher-level API, but it's particularly suitable for creating web content.
The basic Atom Syndication Format as defined by RFC 4287 has a pretty strong slant towards weblog entries, which is no surprise since it was created by a bunch of bloggers. However, part of the Activity Streams effort has been to find ways to expand Atom to make it possible to model other common social web objects such as people, events, photos, etc via Atom. If you apply the activity streams extensions for representing such objects to the AtomPub model you suddenly have a general API for submitting, editing and deleting anything that's catered for by the activity schema specification. But we're back in XML now, right? How can we get from here to JSON?
There has been a number of efforts to define mappings between Atom and JSON, many of them trying to achieve lossless round-tripping. I'm of the opinion that the XML and JSON model are so radically different that you're never going to achieve a lossless transformation of arbitrary XML (which is what Atom is once you augment it with extensions) to JSON. If it was that easy, then we'd already be doing this to go from XML to our language's intrinsic data structures and we wouldn't need JSON!
But if we assume for the moment (and this is certainly not true today, but is a goal) that Atom and AtomActivity (along with its dependencies) together provide a rich enough vocabulary to describe 90% of social objects users deal with on the social web, can we define a JSON vocabulary that refactors only these features into a non-extensible-but-good-enough standard JSON schema? I think we can!
So today I'd like to unveil my first draft of The JSON Syndication Format. While far from complete, it currently describes a basic data model inspired by the basic Atom spec and some bits and bobs from elsewhere. Ultimately I think this format should combine the most important features of the following specifications:
- The Atom Syndication Format
- Atom Threading Extensions
- Atom Feed Paging and Archiving
- Atom Media Extensions
- Atom Activity Extensions
If you read the spec as it stands today you'll note a few interesting things that are not direct mappings from Atom. Firstly, the various different ways of representing content and other text properties in Atom are not supported: you'll use HTML and you'll like it. Secondly, I'm intending to use the PortableContacts schema to describe people rather than a simple mapping of the Atom Person construct.
Since the basic model of AtomPub is agnostic to representation format, it's easy to substitute out application/atom+xml for the two new media types described in this specification. While I doubt Atom and RSS are going to go anywhere for syndication feeds anytime soon, it's clear that Atom (and other XML formats) are on the way out for APIs, so I hope that something like JSON-Syn over AtomPub can be useful as a general social web CRUD protocol that does not require each provider to invent its own schema.
It's unlikely that I'll work much more on JSON-Syn other than this initial prototype until the Activity Streams specs are further along, because the research there will give a better idea of what metadata properties are useful to include in JSON-Syn. The lack of an extensibility mechanism is of course quite limiting, but there's nothing to stop someone who's doing something unusual from inventing a new JSON-based object model, publishing that in an open specification and applying AtomPub principles to that too.
This is just a proof-of-concept effort for now, and I'm sure there are flaws in my approach, but my hope is that we can start moving again towards provider-agnostic APIs despite having refocused efforts on a new serialization format.
Very well put! I fully agree, and hope that baby won't be thrown out with the bath water -- there is more to format/API/protocol design than data serialization aspects. And close decoupling between internal and external representations is an anti-patter for public APIs: whereas coupling can work well (due to lower initial overhead, more convenience) for internal use cases -- which are coupled by nature -- it does not for intra-company interfaces.
Posted by: Tatu Saloranta | 04/13/2010 at 11:43 AM