MIKESTOWE.COM

you are here

More Objections to HATEOAS

This week on the MuleSoft blog I took a look at Hypermedia, HATEOAS, and common arguments for and against Hypermedia.  However, the list of objections is really too long to summarize in a quick, introductory post.  Shortly after writing my hypermedia post for MuleSoft I came across the post “RESTisential Crisis over Hypermedia APIs” by Jerome Louvel. In his post, Jerome describes several of the arguments he heard against REST.  As such, I just quickly wanted to address the concerns or arguments raised against hypermedia:

A good API doesn’t change

This is absolutely false in every regard as APIs evolve over time.  A good API should not break BACKWARDS COMPATIBILITY, but it will change, just as your application and architecture will change over time.  The only reason an API should not change is if you are no longer developing your application or API.  Otherwise, to suggest that “a good API doesn’t change” is just nonsense.

Secondly, this argument completely disregards the aspect of HATEOAS, or using Hypermedia as the Engine of Application State.  This means that because REST is stateless you can still tell the client what actions can be taken on a particular object.  For example, in a singular collection you may have users with different privileges, or users who are suspended, and of course users who are not.  Based on their roles or flags you may be able to do certain actions with some users, but not with others.  This is a key component that hypermedia provides that would otherwise be unavailable- requiring multiple calls with intense checks to see if the action attempted was successful or not.

Versioning doesn’t work

This I couldn’t agree with more, which is while I think it is important to plan for and implement versioning, it is just as important to view versioning as a necessary evil.  Plan for it to happen, but then try to avoid it by carefully planning your API and utilizing spec driven development.  Hypermedia does not solve the versioning problem, although it could let you direct different versioned users to different resources.

Hypermedia destroys resource location

The argument made here is a complete facade.  Without hypermedia developers are required to hardcode the links into their application as they have no other way of accessing them.  To suggest that by giving users links via hypermedia that they might hardcode them as a shortcut is to say that the negative aspect of hypermedia is that some developers won’t take advantage of it, but will rather do things the way they already currently are.

Hypermedia makes sense for humans, not machines

Hypermedia is designed to be interpreted.  It is important to remember that we use hypermedia within applications on a regular basis, most notably something called HTML – the Hypertext Markup Language which is interpreted by the browser and then displayed to the user.  In the same sense, the client application would interpret the hypertext links, passing the available options on to the user.

Utilizing hypertext links within an API does not require a user to look at those links and determine what action they should do, but rather a client smart enough to interpret how to use them.  In plain language, this could be something as simple as:

PHP
1
2
3
if (isset($results->_links->edit)) {
/* ... */
}

Here the code is simply checking to see if the link is available, and if so providing the appropriate action based on it.  This means that we are able to take advantage of the application’s rules, and not try to guess and mimic them on our own, while also having the most up to date information and URI for that action.  A better example of this is shown on the MuleSoft blog.

What’s so bad about out-of-band?

I think anytime you have to start a question with “what’s so bad” you are already self-defeating.  As I stated in the MuleSoft blog, hypermedia does NOT replace well written documentation.  It does, however, provide discovery, help developers understand the path and flow of the API, and provide a layer of flexibility that allows the developer to write his client in such a way that he can take advantage of the hypertext links.  In other words, nothing is “bad” with having well written documentation outside of the API, but it is important to acknowledge that hypermedia and documentation are not one in the same.  In fact, the HAL spec lets you link your resource links to the out-of-band documentation.

What documentation does not do, however, is provide an engine of application state, nor does it tell the developer what actions are available for that specific item.  In regards to being discoverable, hypermedia lets your developer explore your API without having to go back to documentation each time they make a call or access a resource to see what they can do, and with the expansion of new API tools, I think we will find API discoverability and exploration becoming more and more crucial.

Are hypermedia APIs that different from WADL?

Yes.  WADL is a definition language, similar to RAML, Swagger, or API Blueprint.  It does not interact with API calls, nor does it provide an engine of application state (noticing a pattern here?).  WADL was a decent first attempt at trying to solve the self-documenting problem for RESTful APIs, and since then new specs have arisen that make spec driven development possible – as well as API discoverability (outside of the API), documentation, and exploration (outside of the API) easier.  However, none of these would claim to be a replacement for hypermedia as the overall intent of these specs is completely different.

A Web analogue

This takes us away from hypermedia and instead focuses on code-on-demand, which is the only optional REST constraint.  Given the purpose of this blog post (and my already long rant), I will save this for another time.

What seems to be really good about REST?

This one likewise focuses on REST as a whole and not solely on hypermedia.  I think it is no secret that I am a fan of REST, and that I believe you will find several advantages to it over other types of web services.  Here are just a few:

soap_vs_rpc_rest.fw

Chart courtesy of MuleSoft

Share this Page:
Facebook Twitter Linkedin Reddit Tumblr Email

2 Responses to “More Objections to HATEOAS”

  • Thanks Mike. Interesting and detailed post.

    What I’d like to see discuss is what is the context of your comparison between REST, RPC and SOAP. REST was designed to solve a very specific use case and is not a good fit for significantly different use cases. Roy T. Fielding clearly warns about this in his dissertation.

    In this project, I have tried to define an alternative architecture style for Web APIs that would help moving the discussion beyond the current REST versus … debate:
    http://restlet.github.io/web-api-style/

    Best regards,
    Jerome

    • mike says:

      Hey Jerome,
      The chart is taken from another post where I tried to emphasize understanding the type of API you are building (whether it be SOAP, RPC, REST, etc) and understanding why you chose that particular API. Each type offers different strengths and weaknesses depending on your goals. To clarify, I do not see REST as the perfect solution for every API, however, I think it is a good solution – and one that should definitely be considered to see if it meets your and your clients needs. The original post can be found here.

      As for Web API, I think it is an interesting concept. It’s something I have to look more into, although I am curious about your deviation from the uniform interface and code on demand. But definitely interested in learning more about your architecture as well as the thought process behind it :)

Leave a Reply

Your email address will not be published. Required fields are marked *