November 2016

As soon as you get to APIs, and particlarly RESTful APIs, you hear about hypermedia.

It was a strange concept to me. One that I wasn’t able to explain for years after being involved with the web.

<a>

Here’s my definition: hypermedia is any format where one document can link to another document.

The obvious answer is that HTML is a hypermedia format. It’s easy to take it for granted.

But once that’s obvious, there are other formats you can see linking to documents:

• CSS is a hypermedia format, because you can use the url() format to include another file.
• Markdown is a hypermedia format. But that goes without saying, because it just compile out to HTML.
• Freemind mind maps are a hypermedia format. You can make a node link to another mind map, or just out to a URL.

When it comes to JSON APIs, a big downfall is that JSON is not a hypermedia format. There’s no way to “link” to another JSON document. There are standards that build on top of it, like JSON API. If I’m not mistaken, that’s a media type… and my understanding of the terms gets a little vague.

For RESTful APIs, the “HATEOS” constraint doesn’t seem so scary anymore. It means that you’re using links as a way to transition from one state to another.