What is HATEOAS and how does it apply to RESTful APIs? Join the author as he demystifies the concept using familiar analogies.
- [Instructor] We've talked about how RESTful APIs represent resources and links between resources. There's one other big piece to the RESTful puzzle, though, and it's one of the distinguishing features of REST. That feature is HATEOAS, or Hypermedia as the Engine of Application State. Let's unpack what this means. The big idea of HATEOAS is that the responses from the API tell the client what it can do in the API. Here's how that works, when the client retrieves a resource, the response not only includes the details of the resource, but also a set of links that the client can use to either get additional information or change some state in the application.
For example, a response that represents a room in the hotel could have links that the client could follow to view all the bookings for that room, create a new booking by sending a post request, or delete the room by sending a delete request. Let's imagine that the ability to delete an entire room was something that only an administrator could do. If the current user was not an administrator, the API could omit that link from the response. This means that the client only has to look at the API responses to understand what it can do. Another way to say this is, what actions are possible varies depending on the resource and the application state, and that's represented by the response document that's returned to the client.
That's why it's called Hypermedia, which is the response, as the Engine of Application State. One implication of HATEOAS is that the client should not need any out-of-band information or any rules about how the API works. It just needs to look at the responses to understand what is possible. To understand this idea even further, think about how a web browser works. When you tell your web browser to go get wikipedia.org, it doesn't have to understand any special rules about how Wikipedia is organized or how to navigate the site, it just receives a document from the server that tells it how to render the page, and includes links to other places you can navigate on the site.
Depending on the page, the response may contain a form that you can submit to change some state in the application, such as logging in, creating a new article, and so on. We'll keep this example of how a web browser interacts with a website in mind as we design a REST API with the principles of HATEOAS. To recap, the HATEOAS constraint implies that a REST API should return responses to the client that include links to any actions that are possible on that resource, as well as navigation links to other places in the API when appropriate. If an action is possible in the API, it should be a link in the appropriate resource.
In the earlier examples, the response documents were XML or HTML, this applies to APIs that return JSON as well. Just like a website has a root or index page, the API should have a place where the client can start and it should be possible to navigate anywhere else in the API from that one starting point. Finally, there should be no need for the client to have any out-of-band or external information or documentation about the API. In other words, the API should be self-documenting enough that it's possible to use it only by reading the responses without having to read separate documentation.
There's plenty more to explore. If you'd like to learn more and dig even deeper into the best practices around building RESTful APIs, I'd recommend the following resources: the course Learning RESTful APIs, Martin Fowler's article on the Richardson Maturity Model, and the books REST in Practice and RESTful Web Services Cookbook. Next, we'll dig into the HTTP methods that are commonly used with RESTful APIs.
- What is RESTful design?
- Building a new API with ASP.NET Core
- Using HTTP methods
- Returning JSON
- Creating RESTful routing with templates
- Securing RESTful APIs with HTTPS
- Representing resources
- Representing links
- Representing collections
- Sorting and searching collections
- Building forms
- Adding caching to an ASP.NET Core API
- Configuring user authentication and authorization