End-to-End Hypermedia: Choosing a Media Type
So you’ve decided to make the leap and build a hypermedia-rich API. Hopefully, this decision came from necessity and not boredom, but that’s a post for another day.
At this point, you’re presented with a bit of a problem. You have 3 main options for choosing/designing a media type:
- Pick a standard
- Design your own
- Extend a standard
As much as possible, I’d try to go with a standards-based approach. People with much more time on their hands and much more passion for you have thought about these problems for years, and probably have thought about more scenarios than you’re thinking of right now.
Instead of choosing media types in a vacuum, how would one compare the capabilities and intentions of one media type versus another? One way is simply to look at the design goals of a media type. Another is to objectively measure the level of hypermedia support and sophistication of a media type, with H Factor:
The H Factor of a media-type is a measurement of the level of hypermedia support and sophistication of a media-type. H Factor values can be used to compare and contrast media types in order to aid in selecting the proper media-type(s) for your implementation.
H-Factor looks at two types of support, links and control data, and different factors inside those.
For example, HTML supports:
- Embedding links
- Outbound links
- Templated queries (a FORM with GET)
- Non-idempotent updates (a FORM with POST)
- Control data for update requests
- Control data for interface methods (POST vs GET)
- Control data for links (link relations – rel attribute)
But doesn’t support:
- Control data for read requests – links can’t contain accept headers, for example
- Support for idempotent updates – you have to use XHR for PUT/DELETE
With the quantitative and qualitative aspects factored in with client needs, you’ll have what you need to pick a media type. Unless you’ve already decided that this is all way too complex and run back to POJSOs, which is still perfectly acceptable.
Making the choice
There are a *ton* of popular, widely used, hypermedia-rich media types out there:
And probably a dozen others. At this point, just be warned, you’ll probably spend upwards of a week or so to decide which variant you like best based on your client’s needs. You also don’t need to decide a single media type – you can use collection+json for collections of things, and HAL for single entities if you like.
One other thing I found is no single media type had all the pieces I needed. In my real-world example, I chose collection+json because my client mainly displayed collections of things. Show a table, click an item, then display a single thing with a table of related things. It didn’t need PUT/DELETE support, or some of the other control data. I just needed control data for links and a way to distinguish queries versus forms.
But collection+json didn’t *quite* have all the things I needed, so I wound up extending it for my own purposes, which I’ll go into in the next post.