Menu
One of the core ideas behind HATEOAS is that clients should be able to start from single entry point URL and discover all exposed resources and state transitions available for those. While I can perfectly see how that works with HTML and a human behind a browser clicking on links and "Submit" buttons, I'm quizzed about how this principle can be applied to problems I'm (un)lucky to deal with.
I like how RESTful design principle is presented in papers and educational articles where it all makes sense, How to GET a Cup of Coffee is a good example of such. I'll try to follow convention and come up with an example which is simple and free from tedious details. Let's look at zip codes and cities.
Let's say I want to design RESTful api for finding cities by zip codes. I come up with resources called 'cities' nested into zip codes, so that GET on http://api.addressbook.com/zip_codes/02125/cities returns document containing, say, two records which represent Dorchester and Boston.
My question is: how such url can be discovered through HATEOAS? It's probably impractical to expose index of all ~40K zip codes under http://api.addressbook.com/zip_codes. Even if it's not a problem to have 40K item index, remember that I've made this example up and there are collections of much greater magnitude out there.
So essentially, I would want to expose not link, but link template, rather, like this: http://api.addressbook.com/zip_codes/{:zip_code}/cities, and that goes against principles and relies on out-of-band knowledge possessed by a client.
Let's say I want to expose cities index with certain filtering capabilities:
GET on http://api.addressbook.com/cities?name=X would return only cities with names matching X.
GET on http://api.addressbook.com/cities?min_population=Y would only return cities with population equal or greater than Y.
Of course these two filters can be used together: http://api.addressbook.com/cities?name=X&min_population=Y.
Here I'd like to expose not only url, but also these two possible query options and the fact that they can be combined. This seems to be simply impossible without client's out-of-band knowledge of semantics of those filters and principles behind combining them into dynamic URLs.
So how principles behind HATEOAS can help making such trivial API really RESTful?
458
HATEOAS stands for Hypermedia as the Engine of Application State and it is a component of RESTful API architecture and design.
HATEOAS is just one of the aspects that adds difficulty to a REST architecture. People don't do HATEOAS for all the reasons you suggest: it's difficult. It adds complexity to both the server-side and the client (if you actually want to benefit from it). HOWEVER, billions of people experience the benefits of REST today.
Hypermedia as the Engine of Application State (HATEOAS) is a constraint of the REST application architecture that distinguishes it from other network application architectures. With HATEOAS, a client interacts with a network application whose application servers provide information dynamically through hypermedia.
I suggest using XHTML forms:
GET /
HTTP/1.1 OK
<form method="get" action="/zip_code_search" rel="http://api.addressbook.com/rels/zip_code_search">
<p>Zip code search</p>
<input name="zip_code"/>
</form>
GET /zip_code_search?zip_code=02125
HTTP/1.1 303 See Other
Location: /zip_code/02125
What's missing in HTML is a rel attribute for form.
Check out this article:
To summarize, there are several reasons to consider XHTML as the default representation for your RESTful services. First, you can leverage the syntax and semantics for important elements like
<a>,<form>, and<input>instead of inventing your own. Second, you'll end up with services that feel a lot like sites because they'll be browsable by both users and applications. The XHTML is still interpreted by a human—it's just a programmer during development instead of a user at runtime. This simplifies things throughout the development process and makes it easier for consumers to learn how your service works. And finally, you can leverage standard Web development frameworks to build your RESTful services.
Also check out OpenSearch.
HTTP/1.1 200 OK
Content-Location: /zip_code/02125
<html>
<head>
<link href="/zip_code/02125/cities" rel="related http://api.addressbook.com/rels/zip_code/cities"/>
</head>
...
</html>
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
