7

I've just found HATEOAS. I think I kind of understand what is stands for, but something is not clear to me.

There is nowhere to be found how can I create the consuming client in HTML. I can imagine that for some links I will generate buttons, for others there will be hyperlinks. This can so far be done.

But how to create the GUI to be independent. I mean

  • how to create the GUI pages in a generic way (layout cannot be part of the api)
  • how to describe data i.e form definition, table content, client will not know how the data looks like(for HTML it is reasonable human can interpret them correctly)
  • how to limit data(user cannot access some fields)

I'm expecting still to have a lot of logic in the front end. Is it even possible to create generic + good looking front end?

8
  • Do you want to build pages/forms automatically based on the format of resources in a REST API? – scriptin Apr 14 '15 at 13:53
  • yes, I'd like to, but don't see how it can be done. Either the server must know about the layout or front-end must know about the layout. First case is not performance optimal as the server must be queried for the template or send the layout, the second one is binding the FE with the API in my eyes strongly(the FE pages knows where to fill data for specific link) – Zveratko Apr 14 '15 at 14:00
  • People do that using some kind of schema. See this for example: JSON Schema Based Editor. Also, check json-schema implementations (UI generation section). – scriptin Apr 14 '15 at 14:04
  • Are you trying to create some kind of generic general-purpose tool, such as a developer tool for browsing HATEOAS web APIs? Or are you creating a web application intended for end-users? – Moby Disk Apr 14 '15 at 14:06
  • More likely application for end users and I was interested in the possibility to change only BE and the FE will still work. I guess this ideas are called "over engineering":-) – Zveratko Apr 14 '15 at 14:13
2

The whole point is that the client doesn't know anything about the details other than the entry point.

Instead of baking the API into the client, the client fetches the document at the entry point, and uses the types of the returned resources to navigate through the results.

With a website, the browser already does this, and the only part that is different is the server, not the client. The point in that case is that the server doesn't have the API baked in, but instead constructs the URLs based on the types of data, and when you make a request instead of routing based on the URL, it looks at the data types and uses those to figure out what is being requested.

Then when you're building a custom GUI client, all you have to do is stubbornly refuse to insert any information about the URL structure. Then you have no choice but to make a request to the entry point URL, parse the types of data returned, use those types to decide which object to use, and then extract the URL from the object.

Normally for a non-web-browser client that means you're walking over an XML tree and you're totally ignoring where in the tree you're at; you're just looking at the type attributes you added. You know where you're at by the types of object at each level. So for example, you request a top level document, and you want to edit the user profile, instead of searching for a path based on an api, you search for the type. You have to bake the types into the client, instead of the API paths. And then the node with the profile type will contain a url to follow. Then the form has a type, too. So even if there are two forms, and your client only knows about one of them, it still fills out the correct one.

Limiting what fields the user can access should not be impacted by HATEOAS.

Neither the server nor the client "knows" (or cares about) the URL layout. You only use type information that you added.

You'll need to get further into the implementation details before it makes much sense.

https://martinfowler.com/articles/richardsonMaturityModel.html explains it in detail with examples.

1

First for some introductory notions

A lot of so called RESTful APIs you can find out there are not actually RESTful because they ignore one of REST's constraints, which is HATEOAS. They are in fact just HTTP WebAPIs, meaning an API that is exposed over HTTP on the web.

You can very easily recognize these HTTP APIs because they put a lot of emphasis on URL structure (URI actually, but I'll use URL for simplicity). To know how to use the API you need to know what URLs it exposes. Then a lot of the interaction of the client with this API is obtained by carefully constructing the right URLs to access on the server. State transitions are obtained by the client having to know how to jump from one URL to another, making sure the transition is valid. The structure and the dynamics of the application are hard coded in the client. Change the structure of these server URLs and your clients stop working as they desperately try to reach a resource identifier that no longer exists.

A true RESTful API respects the HATEOAS constraint. The client doesn't care about the URLs. The client doesn't carefully construct server URLs to call. The client doesn't change state by knowing from what URL to what URL it can jump. The client simply doesn't care. With HATEOAS it's the server that drives the client state changes. The structure and the dynamics of the application is under the server's control. The client just needs to know how to reach the server on a root URL and from there the server guides the client's actions with links in the resources it returns.

The best example of a HATEOAS client is the web browser. You type in an address like softwareengineering.stackexchange.com (the root URL) and from there on you interact with the site based on the links in the pages (i.e. resources) you get back from the server. You interact and navigate with the site by hyperlinks inside the pages (i.e. resources) you get from the server. All of the states you can reach within the softwareengineering.stackexchange.com site are valid because they are presented in each page by the server. The browser just follows those links to other pages (i.e. resources) without having to care about how the the links are built.

For this to work the browser needs to understand the resource with which the server responds. The server and browser understand HTML, understand links inside the HTML, understand images, tables, headers, footers, XML, JSON, etc. That's all the browser needs: how the resources look like and what they mean.

Both a HTTP API and a true RESTful API understand the exchanged media types. The difference is that with a RESTful API those media types contain links with certain meaning that the client uses to navigate (e.g. HAL), while in the HTTP APIs the links are composed by the client. So with a HTTP API the client needs to have extra knowledge about the structure of the server, beyond the media types it exchanges with it.

Now for the actual questions

I'm expecting still to have a lot of logic in the front end. Is it even possible to create generic + good looking front end?

Yes it is. As long as you understand the media types exchanged between client and server (HTML, XML, JSON, watever) you can build the front end however you like. Say your server returns JSON and not HTML. Does that prevent you in any way to build a good looking front-end? It doesn't.

how to create the GUI pages in a generic way (layout cannot be part of the api)

Layout will be part of the client UI. This depends on what resources are exchanged though. Depending on that you can know how generic or specific you can be in displaying them.

how to describe data i.e form definition, table content, client will not know how the data looks like (for HTML it is reasonable human can interpret them correctly)

You can describe them however you like. You understand the media type and what it means. As such, you can decide what the best way to describe them. If for example you get back a "_links" collection (like for example with HAL) you can have them displayed as links in the page, or buttons, or images, or whatever you like.

how to limit data (user cannot access some fields)

This is a broader topic of authentication and authorization. It isn't something HATEOAS related.

0

But how to create the GUI to be independent. I mean

  • how to create the GUI pages in a generic way (layout cannot be part of the api)
  • how to describe data i.e form definition, table content, client will not know how the data looks like

Use either HTML forms, XForms

(for HTML it is reasonable human can interpret them correctly) how to limit data(user cannot access some fields)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.