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.
| Table of Contents |
|---|
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):
...
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 provides the basis of statelessness with our RESTful APIs. That is, servers are not tracking the application state of each and every client. Servers don't track (and don't care what about) the application state of each and every client. Rather, servers (i.e., our APIs) only care about what cares about requested resource state changes when a client requests at the time it calls our API. Our APIs then package up the When the request is made, our API returns resource content (static and hypermedia) as that is appropriate at the that time. Likewise, clients also should not care about the resource state of the server. They 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.
