StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

PORESTful api design, HATEOAS and resource discovery
text
Body
copied!<p>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.</p> <p>I like how RESTful design principle is presented in papers and educational articles where it all makes sense, <a href="http://www.infoq.com/articles/webber-rest-workflow">How to GET a Cup of Coffee</a> 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.</p> <h2>Problem 1</h2> <p>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 <code>http://api.addressbook.com/zip_codes/02125/cities</code> returns document containing, say, two records which represent Dorchester and Boston.</p> <p>My question is: how such url can be discovered through HATEOAS? It's probably impractical to expose index of all ~40K zip codes under <code>http://api.addressbook.com/zip_codes</code>. 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.</p> <p>So essentially, I would want to expose not link, but link template, rather, like this: <code>http://api.addressbook.com/zip_codes/{:zip_code}/cities</code>, and that goes against principles and relies on out-of-band knowledge possessed by a client.</p> <h2>Problem 2</h2> <p>Let's say I want to expose cities index with certain filtering capabilities:</p> <ul> <li><p>GET on <code>http://api.addressbook.com/cities?name=X</code> would return only cities with names matching <code>X</code>.</p></li> <li><p>GET on <code>http://api.addressbook.com/cities?min_population=Y</code> would only return cities with population equal or greater than <code>Y</code>.</p></li> </ul> <p>Of course these two filters can be used together: <code>http://api.addressbook.com/cities?name=X&min_population=Y</code>.</p> <p>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.</p> <p>So how principles behind HATEOAS can help making such trivial API really RESTful?</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload