HATEOAS APIs and front end development

Question

We are developing a tool from scratch based on a Spring backend and VueJs frontend. I am primarily working on the backend and came to know about the HATEOAS principle of developing REST APIs and adopted it. I will confess that one of the reasons for adopting it was the out-of-the-box implementation that Spring provides.

But, our frontend developer is skeptic of using HATEOAS REST APIs for developing the frontend. The APIs are directly linked to the database so if he uses this API only he has to make multiple calls to get relational data. For eg. if he wants to get the book details along with the library id it is in, he needs to make 2 calls, one to get the book details and another call to a link associated with the book response which would give him the library detail. He instead wants a single API call which would have the library id as an additional property withing the book details.

Now of course the front end is not using a single API, there are lots of APIs and I have spent more time developing custom APIs than any backend logic.

I am in 2 minds now as to which way is correct:

1. Front end should make multiple calls if required, which would surely create delays, in order to conform to HATEOAS standards
2. The front end should call custom APIs only and the APIs should be made so that data can be fetched in as less calls as possible.

Which one should be followed?

Answer 1

The benefits of HATEOAS (Hypermedia) are real for both internal and external APIs. However, the tooling is often lacking to take advantage of those benefits.

Let's start with the "problem" of having the make multiple requests to the server. There are several solutions. First of all, if the front-end consistently has to make multiple requests to get what it needs, you may have a data modeling problem. Your API shouldn't simply map 1:1 to your database. Focus on modeling how data flows through the system, rather than modeling the data.

But, even if you do have to make multiple calls, there are several solutions at your disposal. Your most important tool is HTTP Caching. In theory, you should be able to retrieve a resource once, and then keep that local copy of the resource in sync with the server. If you make a change to your local copy, inform the server of the change with a PUT request and keep using your local copy. Checkout this blog for a good explanation of this approach, or get a copy of the book, "REST in Practice" (still the best book on REST I've every read).

If your resources change very frequently on the server, or are frequently changed by other API users, this approach might not be very helpful. Fortunately, there are other options. Some hypermedia formats like Siren and HAL allow responses to return not just the resource requested, but also other resources that it expects you might also want to make followup requests for. I encourage you to check out those media types.

However, the HTTP/2.0 server push feature makes that feature obsolete. This basically solves the same problem, but at the protocol level. I don't know this feature well, so I won't try to explain it further. The problem with this of course is poor server-side support for this feature. Hopefully our web frameworks will catch up soon.

Now let's talk about the biggest problem, the lack of front-end tooling. The main challenge on the client-side is that the front-end has to figure out how to consume the Hypermedia enabled responses from the server. That can be a lot of work and it's not something front-end engineers want to have to concern themselves with, and they shouldn't have to. This is especially true when we start talking about some of the more complicated and more powerful Hypermedia formats such as JSON Hyper Schema. With the right tooling, the front-end engineers shouldn't have even know what links are being followed to get the data they requested.

I know there was no small amount of hand-waving in this answer, but it's a pretty broad and complicated topic. I encourage you to follow some of those links to learn more. I'm hopeful that one day the tooling will be good enough that you don't need to think about this stuff any more. After all, how much do you need to know about HTTP, HTML, an URI in order to use a website like this one. Basically zero, and it should be the same for anyone consuming your API.

One last thing I'll leave you with is that REST is not necessarily the right choice for all use-cases and it's okay not to use hypermedia if it doesn't fit your needs. These days, most people make that decision with a healthy dose of ignorance, but it's a valid question to ask and you are right to be asking it. Make sure you know the trade-offs and best of luck identifying the good sources for information from the bad.

Answer 2

REST is designed to facilitate API stability and reusability over a very long time horizon when you have multiple clients outside of your control. It sounds like your project has a single API client under your control. That being the case, it's very reasonable to tailor your feature set to the needs and wants of that one client. Just make sure the stakeholders understand you're building a single-client product, not something that can be given to the outside world.

Answer 3

Let be honest, HATEOAS is not worth implementing.

However, it sounds like your issue isn't really about HATEOAS. It's about what's included in the model. Even if the api caller already knows all the endpoints they will still have to make two calls, GetBook and GetLibraryWithBookIn, unless you invent a new ViewModel BookWithLibraryInfo and add API methods to retrieve it.

I would advise against this as each user of the API will want different ViewModels, you'll end up with hundreds of them. Sticking to the Models that map to the DB tables is a good policy.

There is an alternative way around the problem, which is to make a second API as part of the website backend.

This would make multiple calls to the APIs, combine the data according to the needs of the website into view models and return them to the front end in a single call.

That way the front end can have the specific view models they need and the API can remain generic and useable by main applications.