The value proposition of Hypermedia

REST is a well-defined architectural style, and despite many misuses of the term towards general Web APIs, can be a very powerful tool. One of the constraints of a REST architecture is HATEOAS, which describes the use of Hypermedia as a means of navigating resources and manipulating state.

It’s not a particularly difficult concept to understand, but it’s quite a bit more difficult to choose and implement a hypermedia strategy. The obvious example of hypermedia is HTML, but even it has its limitations.

But first, when is REST, and in particular, hypermedia important?

For the vast majority of Web APIs, hypermedia is not only inappropriate, but complete overkill. Hypermedia, as part of a self-descriptive message, includes descriptions on:

  • Who I am
  • What you can do with me
  • How you can manipulate my state
  • What resources are related to me
  • How those resources are related to me
  • How to get to resources related to me

In a typical web application, client (HTML + JavaScript + CSS) are developed and deployed at the same time as the server (HTTP endpoints). Because of this acceptable coupling, the client can “know” all the ways to navigate relationships, manipulate state and so on. There’s no downside to this coupling, since the entire app is built and deployed together, and the same application that serves the HTTP endpoints also serves up the client:


For clients whose logic and behavior are served by the same endpoint as the original server, there’s little to no value in hypermedia. In fact, it adds a lot of work, both in the server API, where your messages now need to be self-descriptive, and in the client, where you need to build behavior around interpreting self-descriptive messages.

Disjointed client/server deployments

Where hypermedia really shines are in cases where clients and servers are developed and deployed separately. If client releases aren’t in line with server releases, we need to decouple our communication. One option is to simply build a well-defined protocol, and don’t break it.

That works well in cases where you can define your API very well, and commit to not breaking future clients. This is the approach the Azure Web API takes. It also works well when your API is not meant to be immediately consumed by human interaction – machines are rather lousy at understanding following links, relations and so on. Search crawlers can click links well, but when it comes to manipulating state through forms, they don’t work so well (or work too well, and we build CAPTCHAs).

No, hypermedia shines in cases where the API is built for immediate human interaction, and clients are built and served completely decoupled from the server. A couple of cases could be:


Deployment to an app store can take days to weeks, and even then you’re not guaranteed to have all your clients at the same app version:


Or perhaps it’s the actual API server that’s deployed to your customers, and you consume their APIs at different versions:


These are the cases where hypermedia shines. But to do so, you need to build generic components on the client app to interpret self-describing messages. Consider Collection+JSON:

{ "collection" :
    "version" : "1.0",
    "href" : "",
    "links" : [
      {"rel" : "feed", "href" : ""},
      {"rel" : "queries", "href" : ""},
      {"rel" : "template", "href" : ""}
    "items" : [
        "href" : "",
        "data" : [
          {"name" : "full-name", "value" : "J. Doe", "prompt" : "Full Name"},
          {"name" : "email", "value" : "", "prompt" : "Email"}
        "links" : [
          {"rel" : "blog", "href" : "", "prompt" : "Blog"},
          {"rel" : "avatar", "href" : "", "prompt" : "Avatar", "render" : "image"}

Interpreting this, I can build a list of links for this item, and build the text output and labels. Want to change the label shown to the end user? Just change the “prompt” value, and your text label is changed. Want to support internationalization? Easy, just handle this on the server side. Want to provide additional links? Just add new links in the “links” array, and your client can automatically build them out.

In one recent application, we built a client API that automatically followed first-level item collection links and displayed the results as a “master-detail” view. A newer version of the API that added a new child collection didn’t require any change to the client – the new table automatically showed up because we made the generic client controls hypermedia-aware.

This did require an investment in our clients, but it was a small price to pay to allow clients to react to the server API, instead of having their implementation coupled to an understanding of the API that could be out-of-date, or just wrong.

The rich hypermedia formats are quite numerous now:

The real challenge is building clients that can interpret these formats. In my experience, we don’t really need a generic solution for interaction, but rather individual components (links, forms, etc.) The client still needs to have some “understanding” of the server, but these can instead be in the form of metadata rather than hard-coded understanding of raw JSON.

Ultimately, hypermedia matters, but in far fewer places than are today incorrectly labeled with a “RESTful API”, but is not entirely vaporware or astronaut architecture. It’s somewhere in the middle, and like many nascent architectures (SOA, Microservices, Reactive), it will take a few iterations to nail down the appropriate scenarios, patterns and practices.

About Jimmy Bogard

I'm a technical architect with Headspring in Austin, TX. I focus on DDD, distributed systems, and any other acronym-centric design/architecture/methodology. I created AutoMapper and am a co-author of the ASP.NET MVC in Action books.
This entry was posted in Architecture, REST. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • Nice article. I’m glad someone finally addressed this in a sane and rational manner.

  • housecor

    Brilliant post Jimmy. Totally agree. Love seeing such a simple concise description of the place where HATEOAS makes sense.

  • Phil Sandler

    Nice post. I will start pointing people toward this post when I am trying to convince them that (1) REST is not what they think it is and (2) that they really don’t need “real” REST.

  • Pingback: The Morning Brew - Chris Alcock » The Morning Brew #1701()

  • Pingback: The value proposition of Hypermedia | I can exp...()

  • Tomasz Masternak

    Nice post. One thing to point out though. I would say there is one implicit assumption in the example you gave for when REST is a valid approach. UI on the client when auto-generated will very unlikely be a competitive advantage of the product.

    • jbogard

      But reactive might, no? Multiple languages, drop-downs that get their lists from the server etc.

      • Tomasz Masternak

        I agree that UI will be flexible and will adjust itself to changing resource structure and in many cases it’s definitely worth the effort. However in more complex scenarios flexibility could lead to a lot of overhead which brings significant cost. For example in case of collections I can imagine that in one application they can be rendered as lists, timelines, carousels etc. depending on location/context etc. To support that we probably need to change/extend format.

        • Frantisek Kaduk

          Totally agree and that’s the reason it can be used just for very limited set of scenarios, IMHO.

          I look at it like: server provides responses in the hypermedia format but my UI won’t be autogenerated. My UI will try to understand/parse the content and be fine-tuned. And that’s where it usually ends.

          • Philippe Marsteau


  • Geoffrey Braaf

    Great post. I have always been a fan of HAL. In the .NET space there are lots of resources for working with such API’s. (WebApi.Hal, HalClient.NET are some i’ve personally been involved in)

    There’s one thing i’d like to mix. In order to avoid clients to hard-code resource uri’s it’s a good practice to generate long (preferably changing) uri’s. This forces client developers to follow REL’s, and thus be truly adaptive. (see also:

  • John Teague

    There are a couple of other benefits to consider:
    *Multiple Clients, one api*. You hinted at this,but I think it should be mentioned explicitly. This is why I think the real sweet spot is for mobile applications can benefit from this. Now that the client is decoupled, you can build out your client apis as time and resources allow without trying to time all application upgrades with api upgrades.

    *Fault tolerance*. As you mentioned, you’re app can absorb new changes. But what’s more likely is that you will not be able to automatically accept new fields. There’s almost always addtional work / processing when these changes occur. *But* your client applications are now fault tolerant to api changes. If the client doesn’t know what to do with something new, it can just ignore it and it won’t break.

  • Pingback: From my reading list #17 – October 13th, 2014 | Pascal Laurin()

  • Pingback: The Baeldung Weekly Review 38()

  • Given your parameters for the “vast majority of Web APIs”, I would go further and say that most of those cases don’t need to be “APIs” at all. The only reason they are built as APIs is due to our current fascination with “SPAs” .

    However, if one used server-generated html, suddenly the responses are “hypermedia”. :-]

    The biggest issue I see with APIs built for “developers outside of our organization” is that there is rarely a clear conception as to vision for the API beyond, “our marketing folks want to be able to say we have an API”. That makes it difficult to offer suggestions for API design. Yet, in that case, hypermedia has benefits because “our organization” doesn’t have control over the clients.

  • Dave Van den Eynde

    There’s another value proposition in REST that you didn’t touch, and I believe it’s the most important reason that REST exists for: scalability.

    If you think of the Web as a global mesh of resources that link to each other, it’s not a stretch to consider that if your API is RESTful, you can scale it beyond a single domain. I could, for example, create links between resources from different systems, different hosts, different companies, even different vendors, as long as the client is capable of handling the media types that are served.

    This is a different form of scalability, one that is not related to the “vertical” or “horizontal” scalability of a single system, that is why the Web has scaled beyond anything that could have been predicted by the inventors of the Web.

    • Dave Van den Eynde

      In addition, I don’t believe that using a “standard” JSON format like HAL or Collection+JSON is a prerequisite to having a RESTful API. It’s all about media types and links.

    • jbogard

      Oh, there’s a lot more value propositions to REST that I didn’t touch – I was only focusing on the value proposition of hypermedia.

  • Ayesha Ahmed

    Helloo All friends if you are geting bored then i have a very nice chat room where you can find pakistani girls, Indian Girls, Uae Girls, Uk Girls, Adult Girls, Dating Girls, Canada Girls, Islambad Grisl, Multan Girls Chat Room, If You Wana Join This Chat Room Then You Do Not Need Any Typ Of Registration Just Enter Your Nick And Enjoy A Pakistani Chat Rooms

  • Reddy I. Bell

    I was somehow disturbed by the enthusiasm of the article, since I hold you in high esteem for your critical thinking and pragmatism (endebted for life for the onion architecture), So it was a pleasure to see that you too had the taste of vaporware in your mouth in the last paragraph.

    I agree with you that we might gain clarity and find relevant use cases down the road. But in the meantime the current iteration really sounds like reinventing HTML and web browsers, with the added abberation of designing APIs for clients that at present time do not, will not – and perhaps cannot – exist.

    Anyway, good stuff Jimmy, thanks for keeping on delivering throughout the years.