End-to-End Hypermedia: Making the Leap

REST, a term that few people understand and fewer know how to implement, has become a blanket term for any sort of Web API. That’s unfortunate, because the underlying foundation of REST has a lot of benefits. So much so that I’ve started talking about regular Web APIs not as “RESTful” but just as a “Web API”. The value of REST for me has come from the hypermedia aspect of REST.

REST and hypermedia aren’t free – they significantly complicate both the building of the server API and the clients. But they are useful in certain scenarios, as I laid out in talking about the value proposition of hypermedia:

• Native mobile apps
• Disparate client deployments talking to a single server
• Clients talking to disparate server deployments

I’ve only put one hypermedia-driven API into production (which, to be frank, is one more than most folks who talk about REST). I’ve attempted to build many other hypermedia APIs, only to find hypermedia was complete overkill.

If your client is deployed at the same time as your server, lives in the same source control repository, hypermedia doesn’t provide much value at all.

Hypermedia is great at decoupling client from server, allowing the client to adjust according to the server. In most apps I build, I happily couple client to server, taking advantage of the metadata I find on the server to build highly intelligent clients:

In this case, my client is the browser, but my view is intelligently built up so that labels, text inputs, drop downs, checkboxes, date pickers and so on are created using metadata from a variety of sources. I can even employ this mechanism in SPAs, where my templates are pre-rendered using server metadata.

I don’t really build APIs for clients I can’t completely control, so those have completely different considerations. Building an API for public consumption means you want to enable as many clients as possible, balancing coupling with flexibility. The APIs I’ve built for clients I don’t own, I’ve never used hypermedia. It just put too much burden on my clients, so I just left it as plain old JSON objects (POJSONOs).

So if you’ve found yourself in a situation where you’ve convinced yourself you do need hypermedia, primarily based on coupling decisions, you’ll need to do a few things to get a full hypermedia solution end-to-end:

• Choose a hypermedia-rich media type
• Build the server API
• Build the client consumer

In the next few posts, I’ll walk through end-to-end hypermedia from my experiences of shipping a hypermedia API server and a client consumer.