What is HATEOAS?

With HATEOAS, RESTful web services provide information dynamically through hypermedia. Hypermedia is a part of the content that you receive from a REST call response. This hypermedia content contains links to different types of media, such as text, images, and videos.

Hypermedia links can be contained either in HTTP headers or the response body. If you look at GitHub APIs, you will find that GitHub APIs provide hypermedia links in both headers and the response body. GitHub uses the header named Link to contain the paging-related links. Additionally, if you look at the responses of GitHub APIs, you’ll also find other resource-related links with keys that have a postfix of url. Let’s look at an example. We’ll hit the GET /users resource and analyze the response:

$ curl -v https://api.github.com/users

This command execution provides an output similar to the following:

*   Trying 20.207.73.85:443...* Connected to api.github.com (20.207.73.85) port 443 (#0)
… < more info>
…
> GET /users HTTP/2
> Host: api.github.com
> user-agent: curl/7.78.0
… < more info >
< HTTP/2 200
< server: GitHub.com
< date: Sun, 28 Aug 2022 04:31:50 GMT status: 200 OK
< content-type: application/json; charset=utf-8
…
< link: <https://api.github.com/users?since=46>; rel="next", <https://api.github.com/users{?since}>; rel="first"
…
[
  {
    "login": "mojombo",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url":
        "https://avatars.githubusercontent.com/u/1?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/mojombo",
    "html_url": "https://github.com/mojombo",
    "followers_url":
        "https://api.github.com/users/mojombo/followers",
    "following_url":
"https://api.github.com/users
/mojombo/following{/other_user}",
    "gists_url": "https://api.github.com/users/mojombo/gists{/gist_        id}",
    "starred_url":
"https://api.github.com/users/mojombo/starred{/owner}{/repo}",
    "subscriptions_url":
        "https://api.github.com/users/mojombo/subscriptions",
    "organizations_url":
        "https://api.github.com/users/mojombo/orgs",
    "repos_url":
        "https://api.github.com/users/mojombo/repos",
    "events_url":    "https://api.github.com/users/mojombo/events{/        privacy}",
    "received_events_url":
       "https://api.github.com/users/mojombo/received_events",
    "type": "User",
    "site_admin": false
  },
  …
  … < more data >
]

In the preceding output, you’ll find that the Link header contains the pagination information. Links to the next page and the first page are given as a part of the response. Additionally, you can find many URLs in the response body, such as avatar_url or followers_url, which provide links to other hypermedia.

REST clients should possess a generic understanding of hypermedia so they can interact with RESTful web services without having any specific knowledge of how to interact with the server. You just call any static REST API endpoint, and you will receive the dynamic links as a part of the response to interact further. REST allows clients to dynamically navigate to the appropriate resource by traversing the links. It empowers machines, as REST clients can navigate to different resources in a similar way to how humans look at a web page and click on any link. Put simply, the REST client uses these links to navigate.

HATEOAS is a very important concept of REST. It is one of the concepts that differentiate REST from RPC. Even Roy Fielding was so concerned with certain REST API implementations that he published the following blog on his website in 2008: REST APIs must be hypertext-driven (https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven).

You must be wondering what the difference between hypertext and hypermedia is. Essentially, hypermedia is just an extended version of hypertext.

What is the difference between hypermedia and hypertext?

As Roy Fielding states: “When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions. Hypermedia is just an expansion on what text means to include temporal anchors within a media stream; most researchers have dropped the distinction. Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types.”

Now that you are familiar with REST, let’s explore REST best practices in the next section.