Page History

In our What is REST? article we focused on a few of the important constraints of REST that are relevant to the SRP HTTP Framework. When discussing the Uniform Interface constraint, we provided an introduction to the concept of Hypermedia As The Engine Of Application State (or HATEOAS for short). In our summary of the concept of HATEOAS, we emphasized its importance but suggested the reader visit this present page to understand why HATEOAS is important.

Quick Answer

This Wikipedia article on HATEOAS nicely summarizes some key objectives and benefits of HATEOAS, so we will cite these here (the emphasis in the below citations are ours):

...

• A link to the related customer resource (e.g., GET /customers/1).
• A link to each related item on the order (e.g., GET /orders/1234/lineItems/1).
• A link to the shipping vendor's tracking information (e.g., GET https://tools.usps.com/go/TrackConfirmAction?tLabels=9374859697090312216947).
• A link that allows the visitor to cancel the order (e.g., DELETE /orders/1234).
• A link that allows the visitor to see all open orders (e.g., GET /customers/1/openOrders).

Each of these links are capable of changing the application state (i.e., the resource content as it exists in the client at a specific point in time). Note, however, that some of these links simply request additional resource content (i.e., via the GET method) but links are also used to make changes to exist to request a change to the resource state (such as cancelling the order). The important point is that all of these links were provided by the server at the time the resource was requested. This implies that the server used the resource state (i.e., the resource content as it exists in the server at a specific point in time) to determine which application state links were applicable when the request was made.

This describes a type of functional contract. Servers inform clients what can be done using through hypermedia and clients inform servers what they want to do using this through the same hypermedia. This is where a stateless design of provides the basis of statelessness with our RESTful APIs becomes possible. Servers are not tracking the application state of each and every client. Servers . That is, servers don't track (and don't care what about) the application state of each and every client. ServersRather, servers (i.e., our APIs in this context, only care about what clients request at the time ) only cares about requested resource state changes when a client calls our API. When the request is made. Our APIs then package up the , our API returns resource content (static and hypermedia) as that is appropriate at the that time. Clients, on the other hand, are likewise not supposed to Likewise, clients also should not care about the resource state of the server. They are should only be concerned with the application state and any responses the server returns when a change in the resource state is made.

Let's revisit the GET /orders/1234 API again. It was previously suggested that the resource might include a link to cancel the order. In order for HATEOAS to work as intended, the server needed to verify that order #1234 was capable of being cancelled at that time. This could rely on a number of factors, such as permissions of the user, whether the product was already shipped, or terms and conditions of this order. In any caseall cases, the server makes a determination and returns or withhold withholds the link (hypermedia) that informs the client that this order may be cancelled. Furthermore, the client must use this link to request a state change (i.e., cancel the order)order cancellation link as needed.

In Summary

HATEOAS is an important design element of APIs that contributes to the uniform interface constraint of REST. However, HATEOAS will be underutilized if clients aren't programmed to expect and utilize hypermedia content. In these cases, RESTful APIs are not much more than ways to access static resource content. Therefore, in order for HATEOAS to be worthwhile, both clients and servers need to support hypermedia content and use it request changes in the resource state.