I’ve been doing some research on Hypermedia APIs recently, as a result of trying to understand the latest state of the art in API design. I came across this post from David Heinemeier Hansson (@dhh) of 37signals fame.
The recurrent hoopla over hypermedia APIs is completely overblown. Embedding URLs instead of IDs is not going to guard you from breakage, it’s not going to do anything materially useful for standardizing API clients, and it doesn’t do much for discoverability.
The thrust of his post is that while adding links into your JSON resource representations is a good idea, believing that this on its own will change the world is not a good idea.
David finishes the post with the following bombshell:
We’ve been down this path to over-standardization of APIs before. It lead to the construction of the WS-deathstar. Let’s not repeat the same mistakes twice. Some times fewer standards and less ceremony is exactly what’s called for.
My reading of this is that this is a dig against efforts like HAL, which aims to provide a standard markup and media type for hypermedia APIs.
This comparison was enough to drive a 56 comment long rant, counter-rant, counter-counter-rant comment storm that I read in full. I came away with two main impressions: 1) People can be pretty mean when angry (potential alien invaders: take note). 2) a little compromise goes a long way.
Speaking as someone who lived through the creeping plague of standards that made up WS-*, I can attest first hand that in the main (with a few notable exceptions), most of these standards hindered rather than helped those of us whose job it was to create good, business meaningful, interoperable services.
It’s not that the standards themselves were necessarily flawed (although in many cases they were), it’s that they were complex, constantly changing, and in many cases solved problems that either people didn’t have, or that HTTP (which is/was still the most common transport for SOAP messages) had already solved. Even when it they did solve a problem (e.g. using WS-Security to secure messages sent over MQ) often the implementation of these standards was spotty and inconsistent, meaning that far from providing the interoperable experience the spec promised, it required us to test that each SOAP client worked with each SOAP server, in order to be sure we were creating services people in our organisations could actually use.
Also, it’s worth noting that the driving force behind most of the WS-* specifications were not architects out in the field, or customers, but product vendors. Being brutal about it, many in the industry take the view that product vendors effectively created a machine for adding additional checkboxes to RFPs, in a kind of procurement arms race that served nobody. I think this is somewhat cynical, in that I remember a few of these standards feeling sensible conceptually at one point or another, even though they feel stupid to me in retrospect. WS-AT, I’m looking at you. None the less, the product vendors were the driving force, and where there is smoke…
JSON over HTTP is an altogether simpler beast.
HTTP has been battle tested and honed for over two decades. HTTP has well defined semantics for finding/creating/updating/deleting resources, built in support for authentication & authorisation, rich support for caching, content versioning and relocation, content type negotiation, compression, the works, all things that were added after the fact to SOAP, despite the fact that more often than not SOAP was running atop HTTP anyway! Not only that, but HTTP is available on (to a good approximation) every PC, server, tablet and mobile phone on the planet, providing the underpinnings of the day to day internet activity of nearly 2.5bn internet users worldwide. It’s fair to say it’s well tested. Far better tested than even the most mature WS-* standards. Although HTTP has some extensibility in the form of ‘X-‘ headers, and custom content types, in practice, these features are used respectfully, and almost always provide optional data – i.e. if a client or server doesn’t understand the header, they can just ignore it. There is no equivalent of SOAP’s mustUnderstand attribute in HTTP. Thankfully.
For these reasons, I think the chances of JSON/HTTP being corrupted this decade in the same way as SOAP was in the last are pretty slim. But this paragraph at the end of the HAL Internet Draft strikes fear into my heart:
Omitting forms from HAL was an intentional design decision that was made to keep it focused on linking for APIs. HAL is therefore a good candidate for use as a base media type on which to build more complex capabilities. An additional media type is planned for the future which will add form-like controls on top of HAL.
This is where DHH does have a point. I really hope this isn’t the beginning of a treadmill of extensions and standards atop JSON/HTTP, something which is currently glorious in its simplicity.
The reality is that simplicity and pragmatism are amoung the most valuable (and sadly rare) features in modern software development. We should tread carefully here.
I’ll be using HAL on future projects, but I’ll be using the smallest subset of it necessary to get the job done.