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.
