Learning 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 take a 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 take a look at an example. We'll hit the GET /users resource and analyze the response:
$ curl -v https://api.github.com/users
This will give you the following output:
HTTP/1.1 200 OK
date: Mon, 28 Sep 2020 05:49:56 GMT
content-type: application/json; charset=utf-8
server: GitHub.com
status: 200 OK
cache-control: public, max-age=60, s-maxage=60
vary: Accept, Accept-Encoding, Accept, X-Requested-With,
Accept-Encoding
etag: W/"6308a6b7274db1f1ffa377aeeb5359a015f69fa6733298938
9453c7f20336753"
x-github-media-type: github.v3; format=json
link: <https://api.github.com/users?since=46>; rel="next", <https://api.github.com/users{?since}>; rel="first"
… <Some other headers>
…
[
{
"login": "mojombo",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://avatars0.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
},
{
"login": "defunkt",
"id": 2,
"node_id": "MDQ6VXNlcjI=",
…
… <some more data>
]
In this code block, you'll find that the "Link" header contains the pagination information. Links to "next" page and "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. Then, REST clients 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 makes use of 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.
You must be wondering what the difference between hypertext and hypermedia is. Essentially, hypermedia is just an extended version of hypertext. As Roy Fielding states: