HATEOAS 101: An Opinionated Introduction. Architectural Styles and the Design of Network-based Software Architectures. Haters gonna HATEOAS — Timeless. Every time someone mentions RESTful web services, there’s always that one person that has to chime in: “That’s not really RESTful, it’s just kinda RESTful.”
I’d always filed that information away, under ‘things to learn later,’ and let it simmer in the back of my brain. I’ve finally looked into it, and they’re absolutely right: 99.99% of the RESTful APIs out there aren’t fully compliant with Roy Fielding’s conception of REST. Is that bad? Before we answer that question, let’s back up a bit: Why aren’t these web services RESTful? Just what is REST, anyway? “The Swamp of POX.” The four levels of REST Let’s start at the bottom and work our way up.
Now, The Swamp of POX means that you’re using HTTP. Level one is where it starts to get interesting. However, there are a set of common operations that are performed on resources, and it seems kinda silly to make a new URI for every operation, especially when they’re shared. Content Negotiation This is content negotiation. Super simple. Richardson Maturity Model. A model (developed by Leonard Richardson) that breaks down the principal elements of a REST approach into three steps.
These introduce resources, http verbs, and hypermedia controls. Recently I've been reading drafts of Rest In Practice : a book that a couple of my colleagues have been working on. Their aim is to explain how to use Restful web services to handle many of the integration problems that enterprises face. At the heart of the book is the notion that the web is an existence proof of a massively scalable distributed system that works really well, and we can take ideas from that to build integrated systems more easily. Figure 1: Steps toward REST To help explain the specific properties of a web-style system, the authors use a model of restful maturity that was developed by Leonard Richardson and explained at a QCon talk.
Level 0 The starting point for the model is using HTTP as a transport system for remote interactions, but without using any of the mechanisms of the web. Bookmarks for earth2marsh tagged 'hateoas' "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 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 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: and that goes against principles and relies on out-of-band knowledge possessed by a client. Problem 2 Let's say I want to expose cities index with certain filtering capabilities: GET on would return only cities with names matching X. GET on would only return cities with population equal or greater than Y. Of course these two filters can be used together: Steve Klabnik.