This post is a response to a question that came up on an internal ThoughtWorks list. The question was, in summary: "Is using JSON more RESTful than minting our own Media Types as required, given that using raw JSON means reading inside the content in order to know what type is being transferred?"

TL;DR: Yes, use a common Media Type and "switch" on the internal data type; create a new Media Type only when something generic and broad and new and useful settles out.

Seems controversial to you? Read on...

Use a Common Media Type

REST works best when you have a truly "uniform interface" that maximises interoperability. You know: HTML that all browsers can understand, not just IE5.5. This is about "self descriptiveness" of your on-the-wire data.

REST (or ROA) is a "dual" of SOA in many ways. One way is that in SOA you can blithely create new schemas, new interfaces, but only have one endpoint "URL". In REST you can blithely create new URLs, but never create new Media Types unless you really have to, and understand the trade-off of this reducing the uniformity of your interface - the self-descriptiveness of your interactions outside of your little world.

Clearly, types and standards evolve, and are never constant, so inevitably Media Types is a grey area in REST, where using a standard - or a non-standard but widely understood type - is indeed, "more RESTful" than using your own; but being "less RESTful" can still be RESTful, as long as you know your audience and are happy with the trade-off. Here is Fielding on the subject.

 

Switch on the Internal Data Type

So, yes, you have to use the Media Type as a very broad switch to your processing logic, and make finer switches based on what you see in the payload. This is the bit that even Roy seems to be a little hesitant on - see my interaction with him in that thread I just mentioned - Roy wants intermediaries to know what's going on without digging into the payload.

But clearly this depends on the level of understanding needed. There is a scale of understanding, even from TCP and octets on the wire, up to UTF-8, up to XML, up to XHTML, up to Microformats, up to your application of all that, and all the layers of understanding possible in your own application. At some point on that stack, you decide to plonk a stake in the ground and declare a level of understanding - a standard, a Media Type - for your HTTP uniform interface and thus for any intermediaries along the path.

I'm not convinced by the intermediaries argument. I want my intermediaries to be pretty dumb, not making decisions for me based on too much understanding, but not full enough understanding. "They know just enough to be dangerous", the saying goes... Bah. Let them know about the difference between HTML and images. That's enough. Even then they mess things up for me, by compressing images for my mobile device when they don't need to.

 

Create a New Media Type only when Something Generic and Broad and New and Useful Settles Out

So we're all gagging for something more intelligent than JSON - at least give us links! But the nature of things is that the next level above JSON will be something that has settled out of "rough consensus and running code" - which means it won't be your application's Media Type! Unless you are lucky enough to have hit on a winner, and were intending for it to be standardised all along.

The "x-*", "*+xml" and "vnd.*" approaches are putting the understanding of the type at the wrong level, and try to side-step the "want to create a standard if we can all agree" intention that the Internet works by. It's like there's a need to be back creating an SOA, or object classes all your own, to fiddle with at a whim.

At least "*+xml" allows the XML level of understanding as a fallback. But what sort of things are in that "*"? Why, nothing less generic than XHTML - "application/xhtml+xml"!

And do you really want to end up in the situation that gave us "application/x-www-form-urlencoded" as one of the most universal Media Types on the planet? Yuk!