How to get along with HATEOAS without letting the bad guys steal your lunch - DevNexus 2020

Editor's Notes

• #4: HATEOAS is nothing new, in fact it’s the aspect of Roy Fielding’s REST work that is often overlooked. I first came across HATEOAS working with a customer many years ago. They raved about how it improved decoupling between their client applications and their backend services.
• #5: Where to start... Well, the main key word in the title is the dreadfull acronym of HATEOAS, so let’s dig a big deeper into that.
• #6: OK, so this is what HATEOAS stands for: Hypermedia As The Engine Of Application State. Definitely a Friday afternoon down the pub naming that one.
• #7: This was my first thought when I read the name.
• #8: So let’s break it down a bit. Hypermedia looks to be pretty important to let’s try to understand that a bit more...
• #9: Here’s the definition from Wikipedia, which actually was one of the most intuitive I found. Read it. Essentially, in the same way Hypertext is a graph of linked text documents, Hypermedia is also a graph of linked things, but in this case they can be of various different types such as images, audio, etc.
• #10: So, are we any wiser?
• #11: And what about this part?
• #12: To try to understand things a bit more, I did a bit of research and came across the Richardson Maturity Model. This isn’t anything new and was written as part of a REST book many years ago. At the time of writing, Martin Fowler reviewed it and wrote up a summary of the model. It follows the standard approach for Capability Maturity Model. They’re designed to measure your organizational/technical maturity against defined criteria. I found this a nice way to think about the elements of REST services. The last layer is HATEOAS and we’ll get to that, but let’s look at each layer. Level 0 – The Swamp of POX You may need more than SOAP to clean off from the Swamp of POX The Richardson Maturity Model starts not at level 1, but at level 0 – the “swamp of POX.” POX in this case stands for Plain Old XML, and represents the most basic functionality expected of an API entering into the Richardson Maturity Model. At this level, HTTP is used as the transport mechanism for every remote interaction, but these interactions don’t utilize the mechanisms inherent in the web. HTTP serves as a basic tunneling mechanism alone. At this level, all API interaction is essentially RPC, a back and forth XML conversation wherein every request and response is nothing more than a chunk of code. This may be useful in some cases, surely, but even in SOAP, the penultimate POX-centric solution, each iteration and evolution is nothing more than wrapping the HTTP process in a complicated envelope. Level 1 – Resources Utilize resources to begin the API maturation process XML conversations work in some scenarios, but they’re not ideal for the complex tasks required of modern API interactions and offerings. For one, POX is inefficient, often transferring superfluous text. Second, by communicating over XML, you’re over complicating what should be an otherwise simple, efficient, and succinct communication. Our first step towards rectifying these issues is to emerge from the swamp of POX by utilizing resources. Resources allow requests to be delivered to the specific resource in question, rather than simply exchanging data between each individual service endpoint. While this seems like a small difference, in terms of function, it’s a complete sea change. In POX, an ill-defined function is simply called from a large body, an aether-like miasma of collated resources and possible points of resolution, and then this function is defined with further complex arguments. By adopting resources rather than XML bodies for communication, we are establishing a type of object identity, calling a particular object and passing arguments to it that are specifically related only to its function and form. Also read: 7 Growing API Design Trends Level 2 – HTTP Verbs Correct HTTP verb usage Now that we’ve moved towards resources, we can start looking at how we interact with those resources. In the POX approach, verbiage often doesn’t specifically matter. POST does what POST does, but GET can in many cases function in much the same way, resulting in an API that often delivers the same data to duplicate verbs. In Level 0 and Level 1, these verbs serve as a tunneling mechanism for your request – in those levels, this is fine, since all the API is really doing is conversing in XML with XML. The problem, however, is that verbiage is different for a reason. Each verb — GET, POST, PUT, DELETE, etc — does something very specific, and these functions often deliver entirely different sets of results when properly addressed – failure to leverage HTTP verbs for their correct usages means that you’re losing a lot of potential functionality for no reason. As a good example, both POST and GET in the POX approach will result in the same return – GET, however, is defined as a safe operation, which opens up a ton of functionality. One such functionality is caching, which can be used to great effect to reduce the amount of processing needed by the API, and an increase in transit efficiency by removing the need to respond to requests that will only generate the same result. All of that is lost, of course, without designing your resources specifically around the verbiage and the expected response. By differentiating the leverage through design at level 2, we can take full advantage of such benefits. For more on HTTP verbiage read: Designing Evolvable APIs for the Web: Interaction Level 3 – Hypermedia Controls HATEOAS delivers more links and information For many developers, level 2 is “good enough”. Proper verbiage and a reduction in XML chatter dependence seems to result in an API that is basically in a usable state, and as such is where many developers feel comfortable with stopping. Unfortunately, this is missing the entire point of this exercise – the final step, level 3, grants certain benefits that should not be ignored. Level 3 implements hypermedia, which can be used to great effect to extend the functionality of an API to new levels. By implementing HATEOAS (Hypertext as the Engine of Application State), we can make the API respond to requests with additional information, and link resources together for more rich interactions. These links can make user experience that much more rich, and can create a web of functionality that results in a more powerful, more efficient, and more useful. Utilizing hypermedia also delivers the ability to update URI schemes without breaking clients, allowing for a greater amount of freedom for development change on the back end. This is not the case before level 3, but the benefits don’t stop there. The simple fact is that an API which does not utilize Hypermedia is functioning at its most basic, least useful level – the fundamentals may be on offer, but the API is self-limiting in the extreme. Related: REST State Machine Revisited The Richardson Maturity Model Guides Development Beyond the reasons noted above, there’s an even greater reason to adopt the Richardson Maturity Model through to level 3. According to Roy Fielding, the creator of the concept of RESTful design, Hypermedia is a prerequisite of true REST. As such, reaching the final third level of the Richardson Maturity Model can be seen as a goalpost for development teams that desire a true RESTful conclusion. All of that being said, the final level of the Richardson Maturity Model is not the end-all be-all for API design. REST is very useful, but there are some cases where SOAP makes sense, and in that case. Even in those cases, of which there are few, level 2 Richardson Maturity Model is still a very good goalpost to reach, as that is where an API comes to depend on resources rather than XML bodies and massive undifferentiated endpoints. Here, we can see where the Richardson Maturity Model really shines. Yes, it’s final levels will result in a RESTful result – but ultimately, the Richardson Maturity Model is a great system by which the maturity of an implementation can be measured. With each maturity requirement of your implementation fluctuating largely due to the requirements of the user, the Richardson Maturity Model can be used as a sort of structure by which development can be guided towards a more complete, more mature result, irrespective of the foundational elements of the API itself. It also adds structure for collaborative development. Any development will naturally start as less mature and evolve towards more mature. Guiding API design solely by features or economic motives without a structure in place can lead to issues. Therefore, technical development must be guided, and it must be structured with a goal in mind. More important than these elements are the structures which fundamentally dictate whether the API is RESTful or not, whether it uses resources or not, and whether it respects standardized verbiage. The Richardson Maturity Model can function as a system to ensure adherence and promote maturity throughout the development lifecycle. A Path Toward API Realization Ahh, out of the swamp. This looks much better. The Richardson Maturity Model is a visual way to gauge the competency of your API. In this article we dissected each layer: Plain Old XML, Resources, HTTP verbs, and hypermedia. Much like Maslow’s Hierarchy, the journey to realization is an upward climb; as your API moves higher, it becomes more fulfilled. While the Richardson Maturity Model is not the only development model on offer in the API landscape, it’s core philosophies are hard to argue against. The simple fact that its ultimate goal, integration of Hypermedia, is considered by Roy Fielding himself to be a prerequisite for REST design should make anyone developing a REST application take notice. Additionally, even when ignoring its RESTful attributes, the Richardson Maturity Model offers a goalpost for development that will result in greater, more fully designed APIs that respond in a more natural, effective, and powerful way. Additional Resources Richardson Maturity Model: steps toward the glory of REST Richardson Maturity Model Act Three: The Maturity Heuristic
• #13: Swamp of POX. POX stands for Plain Old XML, which shows its age.
• #14: So for us, we’re going to talk about Swamp of Plain Old JSON, or POJ.
• #15: With POJ, you have a single service endpoint for all requests. Interactions are RPC style, meaning your calling a remote procedure identified in the body of the request. Because you don’t know the semantics of the procedure you need to use the lowest common denominator Http method of POST (neither safe nor idempotent so can’t be cached or retried).
• #17: Next layer up is Resources and Resource Identifiers. Here, we expose multiple endpoints, one for each resource type. The API becomes more strongly typed because we’re passing the same resource type around. Still passes the procedure in the request and uses POST as the lowest common denominator.
• #21: The existences of a link can be reflected in the UI with an available action. The location can be changed on the server without having to change the client.