Make efficient REST-API calls with HATEOAS

Question

I think I basically understand what HATEOAS is and why you should use it. However, I have some problems with applying this to a real world scenario.

For example:

I would like to display a list of appointments in my client application. An appointment consists of a date, a location and a person. All of this information should be displayed in a table.

My API's response currently looks something like this:

{
  "id": 1,
  "date": "2020-01-01",
  "location": {
    "name": "my office",
    "address": "my street 22"
  },
  "person": {
    "name": "john",
  } 
},   
{
  "id": 2,
  "date": "2020-01-22",
  "location": {
    "name": "your office",
    "address": "your street 30"
  },
  "person": {
    "name": "peter",
  } 
}

Each appointment object therefore also contains all related objects. This makes fetching the data from the REST API efficient from my point of view, since I only need one API call. For example:

api.com/appointments

With HATEOAS the API response would probably look something like this:

{
  "id": 1,
  "date": "2020-01-01",
  "location": {
    "url": "api.com/location/{id}",
  },
  "person": {
    "url": "api.com/person/{id}",
  } 
},    
{
  "id": 2,
  "date": "2020-01-22",
  "location": {
    "url": "api.com/location/{id}",
  },
  "person": {
    "url": "api.com/person/{id}",
  } 
}

I would have to get the related objects through additional API calls.

Let us now assume the following:

I would like to display a list of 100 appointments. Each appointment is assigned to a different person and a different location. So I would need an API call to get all appointments, another 100 API calls to get all locations and another 100 API calls to get all person. That is a total of 202 API calls.

That doesn't sound very efficient to me. Do I have a mistake here or how would HATEOAS work in such a scenario?

user_607033 · Answer

You confuse REST with a database. You can expand nested resources if that's what your clients want to. HATEOAS is more about adding useful operations to your resources, so you can search, read, paginate, modify, create, delete them if you want to. As of the REST API, you should look at it as if it was a webpage. If you want to see all the appointments in a table along with the edit or delete buttons, then you send back a view model for that table along with the links for edit or delete. The REST client normally runs on server side and the application that uses it is a consumer of the REST service. So the REST service is normally not in direct contact with the user and the REST client does not run in the browser though it can be used this way too with single page JS applications, but it was not designed for this usage.

user_54734 · Answer

how would HATEOAS work in such a scenario?

How would you do this with a web page?

There are a lot of designs you could choose, but a perfectly ordinary, backwards compatible to 1990s, choice would be to create a table with 100 rows, with the immediately useful information directly encoded into the table cells, and links to other web pages that might be useful.

And that's fine.

Sometimes, we use this webpage to display a digest of the data, and provide a link that instructs the client how to find a richer view of the data.

And that's also fine.

In other words, you get to choose for yourself which tradeoffs are appropriate for your needs, and design your resource model such that it is in alignment with those needs.

Make efficient REST-API calls with HATEOAS

2 Answers