HATEOAS is an acronym formed from the initials of the words “Hypermedia as the Engine of Application State” and is one of the key features of the REST API architecture. With HATEOAS, clients can use a REST API without knowing (or with minimal knowledge) how to consume it. We will understand better what this means with a simple example a little later.

In this article, I will explain the examples in the Wikipedia article (1) on the subject, combining them with my past experience.

HATEOAS Example

What is the result we expect when sending a request to any endpoint of a REST application? The first thing that comes to our mind is the direct data we want. However, a good REST Api often sends the list/links of other resources related to this resource, possible actions can be taken and the information that can be obtained.

When you enter a website, you can clearly see the links of the actions you can do on the page and say, “If I click here, I enter”, “If I click here, I see the categories”, “If I click here, I can go to the previous page” etc. Similiar to this, a rest API compatible with HATEOAS principles clearly tells the client which resources are available and what the client can do with them.

LET’S SIMPLIFY

Such conceptual sentences can be difficult to understand, so I will simplify them with a short example and then move on to the examples in Wikipedia.

Let’s assume we have requested information about an article from our REST Api. The direct answer to our question will be “Article Title” and “Article Content”. If it is a HATEOAS compatible API it will explain us there are related resources like “Author”, “Comments”, “Categories” etc. Our Rest Client may not know anything about this new entities, but can get the information using the endpoint links provided by the REST API.

EXAMPLES FROM WIKIPEDIA

For example, the example below requests information from the ACCOUNT resource in the form of JSON.

GET /accounts/12345 HTTP/1.1
Host: bank.example.com
Accept: application/vnd.acme.account+json
...

The representative response returned is:

HTTP/1.1 200 OK
Content-Type: application/vnd.acme.account+json
Content-Length: ...
{
    "account": {
        "account_number": 12345,
        "balance": {
            "currency": "usd",
            "value": 100.00
        },
        "links": {
            "deposit": "/accounts/12345/deposit",
            "withdraw": "/accounts/12345/withdraw",
            "transfer": "/accounts/12345/transfer",
            "close": "/accounts/12345/close"
        }
    }
}

The returned answer includes the info we require as well as links to deposit, withdraw, transfer and close links.

Let’s look at the situation where the account balance goes negative in a later request;

HTTP/1.1 200 OK
 Content-Type: application/vnd.acme.account+json
 Content-Length: …
 {
     "account": {
         "account_number": 12345,
         "balance": {
             "currency": "usd",
             "value": -25.00
         },
         "links": {
             "deposit": "/accounts/12345/deposit"
         }
     }
 }

In this case, we see that withdrawal, transfer and closing are not included in the links, but only a deposit link.

We don’t need to create a logic on the client like if account balance is greater than 0 “show this, otherwise hide that” etc. etc.

Relationships are not mentioned in the examples on Wikipedia, but often the API service also sends a list of associated resources and urls from which we can get information about those resources. Shown here is just the basic example, more complex API answers can be returned but the main idea remains the same.

What does HATEOAS provide us?

HATEOAS provides freedom by removing dependencies on connection addresses. Considering that we are developing RESTApi not for our own use, but for clients or the public, it is not possible to define all endpoint URLs inside the client (hard code).

If the response provides applicable links, one can use method names without hardcoding their URL’s in the client. So it is possible to change URLs on the backend without the need to make any changes to the clients, and it will even be possible to give different URLs on a client basis.

Consequently, if you design an API that conforms to any API specification, it will probably conform to HATEOAS. However, knowing the concept, what and why’s will help us to imagine the whole structure more easily.

Sorularınız varsa veya fikir alışverişi yapmak isterseniz yorumlardan, Twitter , LinkedIn veya Instagram üzerinden ulaşabilirsiniz. Sevgiler…

Reference

  1. Wikipedia contributors. HATEOAS. Wikipedia, The Free Encyclopedia. March 18, 2020, 00:21 UTC. Available at: https://en.wikipedia.org/w/index.php?title=HATEOAS&oldid=946088168. Accessed February 23, 2021