There seems to be a couple of common concerns that people have about introducing hypermedia to their APIs. There’s a thread on the api-craft mailing list called “Selling the benefits of hypermedia” where these were voiced. I’d like to address them here:

REST should be simple, and hypermedia only complicates stuff… …it’s much more complicated or complex to write clients to parse and consume links than to read an “id” and add it to an pre-known URI

This is actually not true in the case of hal+json - no parsing is needed since the links are structured around json’s processing model i.e:


Following the above link is actually less complex than having to extract an id and adding it to a pre-known URI template. It also reduces coupling because the client no longer has to maintain the pre-known URI template.

That the paralell frequently established between the success of the web and hypermedia, doesn’t apply to machine API clients since they lack the inteligence that allows people to “navigate” the web and make use of the application controls embedded in representations

I agree with this, to an extent. Machines have no real intuition so some types of affordances (like forms) don’t make a great deal of sense. Having said that, I do think the basic affordance of links (and relations) still presents some significant benefits to a machine API:

Firstly, as touched on above, it reduces coupling between client and server because the client does not need to maintain a knowledge of the server’s URI structure. This can help the server to change its URI structure over time to suit its internal implementation without breaking clients.

Secondly, it makes the API browsable by developers. Browsable because a linking convention establishes a standard way of conveying the next available transitions, and therefore makes the creation of tools for ‘surfing’ across an API possible. See

Thirdly, it makes the API discoverable by developers. With a format like hal+json, custom link relations (i.e. the link identifiers) should be URLs and those URLs should expose the documentation for the given link. This means that the links in the API messages also provide a direct reference to their documentation (since their identifiers refer to their documentation), thus making the documentation part of the API. Combined with browsability; you end up with an API that is fully discoverable by a developer, where they can just hit an entry point to the API, read the documentation for the currently available links in-line, and start exploring outwards from there.

Lastly, links can be used to version portions of an API in a granular way. New/breaking changes to a particular part of an API can be introduced by adding additional link(s) alongside the old. The new/breaking change can diverge from the old path for as long as necessary, and then rejoin the flow further down the line. This allows your API to be delivered in a more iterative style, with many small discrete changes - rather than large changes with an entire API version jump. Smaller deliveries are easier to measure, manage, and result in less overall risk/cost.