HATEOAS (or: Why your API is not RESTful)

Developers who work on Webservices or any kind of API have most likely heard about the RESTful architecture for APIs.

There is a huge misunderstanding on what it takes to make an API comply with the “RESTful” specification. In part this is because the specification is ambiguous on several points, but what I’ve seen is that there’s a huge amount of misinformation and mislabeling out there.

So, many developers have worked on APIs which respond to HTTP verbs (GET, PUT, POST, DELETE), and operate on resources, CRUD-style, and think that’s what it takes to “be RESTful”. And that’s misguided; merely doing that is not enough. Enter HATEOAS: Hypermedia As The Engine Of Application State. Or: You send “hypermedia” in your responses.

Hypermedia is not something recent developers think a lot about, but have grown up with. It’s a concept of diferent “media” (text, audio, video, images) referencing each other. The references we use are hyperlinks.

In other words: HATEOAS means that, just like when you serve a regular webpage developed in any programming language, you send links pointing to the different URLs where actions can be taken. Indeed, this means that the client application (e.g.: a regular web browser) doesn’t need to have knowledge about the server application’s (e.g.: a regular website’s) structure or organization beforehand, but can invoke its behaviour through access points (e.g.: URLs) sent in the server’s response.

The state of the interactions with the server is, then, contained in the response. To keep it up with the browser+website example, the current state of your interactions with the server is implicit in the html, css, and javascript that the server sent your browser.

What does this mean?

A simple way to state it is that your application should be discoverable from a  single endpoint… just like everything you can do on a website you can discover from going to its main page, without looking at the developer’s documentations. If this condition is not covered, then your API does not conform to the RESTful ideal.

If you’re curious, here’s the paper which first describes REST.

A few more words:

  • REST means “REpresentational State Transfer”. If you Transfer some data (resources, for instance) from the server, but not the operations that can be excercised on it from the state the client expressed in its request, are you transfering State from the server to the client?
  • CRUD-style applications are not the only thing that can be done with RESTful APIs. If this looks weird to you, then it’s a great time to read upon the subject.

Thanks for your attention, more content Tomorrow.

Leave a Reply

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