Sergey Shishkin

software craftsmanship in practice

Hypermedia DNA

I played with this little idea for quite some time and finally decided to blog about it. As hypermedia getting traction now (e.g. GitHub API introduced some hypermedia) more people think about standardized ways of doing it. Unfortunately the de-facto standard representational format for machine-to-machine communication on the Web — JSON — doesn’t provide any of the hypermedia factors out of the box.

The most notable standardization effort in this area — Hypertext Application Language — takes in my opinion the all-or-nothing limiting and heavyweight approach: your implementation either complies with HAL or it doesn’t. So implementers who don’t want 100% HAL just roll out their own completely unique media types with no interoperability at all. Can we achieve interoperability and embrace diversity at the same time? It turns out that we can.

Evolutionary Lesson

Nature itself has solved the same problem quite elegantly: every living being carries sequence (the DNA) of standardized parts encoding a unique combination of properties the living being will have. During replication two DNAs are combined to produce a new and unique one.

What if hypermedia types would be defined as combinations of standard building blocks? These small standardized building blocks — hypermedia genes — will describe how exactly that particular hypermedia factor is supported by an implementation. API designers won’t have to decide whether the complete HAL specification meets their needs. An API designer might like HAL link objects, but dislike underscores in attribute names and not need resource embedding. No problem, just cherry-pick useful genes and replicate a new and interoperable hypermedia type.

The Hypermedia Genome

How can these hypermedia genes look like? Small hypermedia features in different flavors like a particular representation of links or ways of reporting errors can be defined, named and catalogued. Last year I started describing a set of such hypermedia controls for JSON named JSON Hypcos (hypco is short for hypermedia control). The list is by no means complete, those are just some of the hypermedia controls I use in my work.

Describing individual hypermedia controls instead of trapping them in all-or-nothing media types has many benefits. Like microformats applied to existing data, standardized hypermedia controls can describe existing API designs giving them standardized semantics.

Client developers can grok new APIs easier, if those APIs are defined out of well-known building blocks. Documenting APIs will also require much less effort, if hypermedia controls become commodity. Generic hypermedia client libraries can hide APIs’ diverse flavors behind equivalent semantic of hypermedia controls, allowing client developers to focus on application semantics instead of the wire implementation of the interface.


The good thing about standardized media types is that we further have standardized means of advertising and discovering client and server capabilities in terms of media types. I talk about the Accept and Content-Type HTTP headers. If individual hypermedia genes become media type description units, we also need content negotiation on this finer-grained atomic level.

First of all, each hypermedia control flavor must be uniquely addressable. URI? Probably. Consider urn:json-hypco:link-object or even shorter urn:hc:lo. Remember that a complete media type will consist of a dozen or more of these. For efficiency multiple hypermedia genes can be combined like this: urn:hc:lo+lr+sl+lh+tu (hypermedia chromosomes?).

API’s complete hypermedia DNA might be advertised by the server with an HTTP response header like Content-Controls: urn:hc:lo+lr+sl+lh+tu urn:foo:bar .... Clients might also declare their level of hypermedia support: Accept-Controls: urn:hc:lv+tu.

What Next?

This blog post is my unofficial request for comments. It is my take at bringing interoperability into the emerging hypermedia API space while still embracing its diversity and evolution. I’m more then excited to hear from anyone interested in the topic.