Welcome!

Microservices Expo Authors: Zakia Bouachraoui, Elizabeth White, Pat Romanski, Liz McMillan, Yeshim Deniz

Related Topics: Microservices Expo, Java IoT, Machine Learning , Apache

Microservices Expo: Blog Feed Post

API Gateway Support for HATEOAS: First Do No Harm

But what is HATEOAS (and how do you pronounce it?)

I often think it's ironic that while the mission of REST is to simplify Web development, REST itself is beset with seemingly complex jargon and architecture patterns. I say "seemingly complex" because, once you look into REST architecture in depth, it actually is simple. In some ways, it's almost too simple. It's easy to rack your brains about some REST pattern, but then realize: It's just how the Web works. I'm reminded of the line from Moliere about the bourgeois gentleman who spends years trying to understand how he could speak in "prose", then he exclaims "Good heavens! For more than forty years I have been speaking prose without knowing it". So it is with REST. HTTP verbs, URLs, and resources are just what we've been doing for years.

There are various levels of REST though, most famously categorized in the Richardson Maturity Model. At the top of this maturity model is HATEOAS. Actually I think "maturity model" is a bit of a misleading name, because ideally you don't want to start with a very brittle URL and then "mature" it to HATEOAS, since that puts undue requirements onto your client applications. It is better to start with HATEOAS principles from the start.

But what is HATEOAS (and how do you pronounce it?). Well, it stands for Hypertext As The Engine Of Application State. As with everything REST, the concepts come from Roy Fielding's paper. The core idea is that the HTTP server serves out links which guide the client as to what they can do with a particular resource. So, for example, if I do a GET on a product listed in a catalog, I receive back a series of links which are the actions I can perform on it. I may be able to get the price of the product via one of the links, order it via another link, get back a description of it via another link, or get back its weight via another link. My application may also may be provided an "up" link back to the main list of products. The powerful concept is that the links are all

the actions my app can take on the resource. So, if I am not allowed to order the product, then I will not be given the "order" link. The client app can then take this into account ("I wasn't served up the "order" link for this particular product, therefore I will not provide the user with the ability to order it"). If you can order it, and do order it, then you may not be served up the "order" link for that product anymore, but (because you've ordered it) you may be served a link to view your order. This is the stateful aspect (it "knows" you've placed the order, and in fact that information is conveyed by the hypertext itself).

Another example is iteration through a set (for example, a list of products). As I am returned back each batch of results (e.g. the first 50, the next 50, etc), I get back a link to the previous batch of results (unless it's the first batch, then there is no "previous" link provided) and to the next batch (unless it's the last batch, then there is no "next" link). In this case also, all possible links are provided back to me. So it is also stateful (when I am on the second batch of results, it "knows" to give me link back to the first batch).

Providing all possible links, right inside the hypertext response, is a powerful concept. It's very different from the SOAP/WSDL world, where you must look at the WSDL in order to find out what actions (operations) are available to you. With HATEOAS, there is no "WSDL", instead the possible actions are in the response. The SOAP analogy would be where each SOAP response contained a WSDL that listed all of the subsequent operations the client could invoke. Another way HATEOAS is different is that, in the SOAP/WSDL world, if the WSDL changes, then SOAP/WSDL client apps must often be rebuilt. With HATEOAS, the service provider can add another capability, and it comes back as a new link in the hypertext responses, but this does not "break" anything. Similarly, removing a capability translates to removing a link, which should already be handled gracefully by the application.

With HATEOAS, the (hypertext) responses guide the client through their interaction with the resource, by providing links to the actions they can perform, so therefore the hypertext pages themselves become the engine of state. Hence the term, Hypertext As The Engine Of Application State.

[ Regarding
pronunciation of HATEOAS, I've heard it pronounced like a breakfast cereal or chip snack ("hate -o's") and also I've heard the edgier "hate yo' ass". ]

So, how does an API Gateway cater for HATEOAS? A key requirement is not to break it. As in medicine, "first do no harm". Consider what an API Gateway does: It provides external-facing APIs to the public, then translates them to back-end (usually on-premise) API calls.


Take for example the following JSON returned by a server to a client. The client has done a GET to get product information. The response includes a link to order the product, and it also an "up" link to go back to a higher-level view.

{
"id": "8000",
"links": {
"self": "http://myBackEndAPI:8000/v5/products/123456"
},
"ordering": [
{
"id": "8000-123456",
"links": {
"self": "http://myBackEndAPI:8000/v5/orders/8000-123456",
"up": "http://myBackEndAPI:8000/v5/8000"
},
"customer_id": "8000",
}
]
}

We see in the response above that the address of the back-end API server (myBackEndAPI:8000) is inside the JSON. When an API Gateway is used, clients go through the API Gateway, and should not go to the back-end API server directly [in fact, usually the API Gateway is cloud-based, and the API implementation is on-premises not directly accessible except through the API Gateway]. Therefore, the API Gateway must selectively replace the address of the back-end API server with the public-facing API server address, and it must do so throughout the responses, whether they are JSON, XML, or another format.

For our example above, the response may become:

{
"id": "8000",
"links": {
"self": "http://api.mycompany.com/v5/products/123456"
},
"ordering": [
{
"id": "8000-123456",
"links": {
"self": "http://api.mycompany.com/v5/orders/8000-123456",
"up": "http://api.mycompany.com/v5/8000"
},
"customer_id": "8000",
}
]
}

When requests come back from the client, it must also selectively change this address information, not only in the request URL but also in the payloads being POSTed or PUT to the REST API.

So how is this done? In the case of Vordel's API Gateway, such content substitution is provided as standard, and is implemented in a high-performance manner so that the URL replacement required to support HATEOAS will not impact on the user experience for your users. Really, what is involved here is analogous to how an application gateway always operates, with the extra stipulation that it must convert information within messages also. But, substituting information within messages is simple with Vordel's API Gateway, and already widely used such as in simple search/replace scenarios. All of this enables Vordel to support HATEOAS for our API Gateway customers.

Read the original blog entry...

More Stories By Mark O'Neill

Mark O'Neill is VP Innovation at Axway - API and Identity. Previously he was CTO and co-founder at Vordel, which was acquired by Axway. A regular speaker at industry conferences and a contributor to SOA World Magazine and Cloud Computing Journal, Mark holds a degree in mathematics and psychology from Trinity College Dublin and graduate qualifications in neural network programming from Oxford University.

Microservices Articles
When building large, cloud-based applications that operate at a high scale, it’s important to maintain a high availability and resilience to failures. In order to do that, you must be tolerant of failures, even in light of failures in other areas of your application. “Fly two mistakes high” is an old adage in the radio control airplane hobby. It means, fly high enough so that if you make a mistake, you can continue flying with room to still make mistakes. In his session at 18th Cloud Expo, Lee A...
In his general session at 19th Cloud Expo, Manish Dixit, VP of Product and Engineering at Dice, discussed how Dice leverages data insights and tools to help both tech professionals and recruiters better understand how skills relate to each other and which skills are in high demand using interactive visualizations and salary indicator tools to maximize earning potential. Manish Dixit is VP of Product and Engineering at Dice. As the leader of the Product, Engineering and Data Sciences team at D...
Lori MacVittie is a subject matter expert on emerging technology responsible for outbound evangelism across F5's entire product suite. MacVittie has extensive development and technical architecture experience in both high-tech and enterprise organizations, in addition to network and systems administration expertise. Prior to joining F5, MacVittie was an award-winning technology editor at Network Computing Magazine where she evaluated and tested application-focused technologies including app secu...
Containers and Kubernetes allow for code portability across on-premise VMs, bare metal, or multiple cloud provider environments. Yet, despite this portability promise, developers may include configuration and application definitions that constrain or even eliminate application portability. In this session we'll describe best practices for "configuration as code" in a Kubernetes environment. We will demonstrate how a properly constructed containerized app can be deployed to both Amazon and Azure ...
Modern software design has fundamentally changed how we manage applications, causing many to turn to containers as the new virtual machine for resource management. As container adoption grows beyond stateless applications to stateful workloads, the need for persistent storage is foundational - something customers routinely cite as a top pain point. In his session at @DevOpsSummit at 21st Cloud Expo, Bill Borsari, Head of Systems Engineering at Datera, explored how organizations can reap the bene...
Using new techniques of information modeling, indexing, and processing, new cloud-based systems can support cloud-based workloads previously not possible for high-throughput insurance, banking, and case-based applications. In his session at 18th Cloud Expo, John Newton, CTO, Founder and Chairman of Alfresco, described how to scale cloud-based content management repositories to store, manage, and retrieve billions of documents and related information with fast and linear scalability. He addresse...
The now mainstream platform changes stemming from the first Internet boom brought many changes but didn’t really change the basic relationship between servers and the applications running on them. In fact, that was sort of the point. In his session at 18th Cloud Expo, Gordon Haff, senior cloud strategy marketing and evangelism manager at Red Hat, will discuss how today’s workloads require a new model and a new platform for development and execution. The platform must handle a wide range of rec...
SYS-CON Events announced today that DatacenterDynamics has been named “Media Sponsor” of SYS-CON's 18th International Cloud Expo, which will take place on June 7–9, 2016, at the Javits Center in New York City, NY. DatacenterDynamics is a brand of DCD Group, a global B2B media and publishing company that develops products to help senior professionals in the world's most ICT dependent organizations make risk-based infrastructure and capacity decisions.
Discussions of cloud computing have evolved in recent years from a focus on specific types of cloud, to a world of hybrid cloud, and to a world dominated by the APIs that make today's multi-cloud environments and hybrid clouds possible. In this Power Panel at 17th Cloud Expo, moderated by Conference Chair Roger Strukhoff, panelists addressed the importance of customers being able to use the specific technologies they need, through environments and ecosystems that expose their APIs to make true ...
In his keynote at 19th Cloud Expo, Sheng Liang, co-founder and CEO of Rancher Labs, discussed the technological advances and new business opportunities created by the rapid adoption of containers. With the success of Amazon Web Services (AWS) and various open source technologies used to build private clouds, cloud computing has become an essential component of IT strategy. However, users continue to face challenges in implementing clouds, as older technologies evolve and newer ones like Docker c...