HATEOAS & Runtime Discovery | The Holy Grail of REST

Many-a-times we think State Transfer (ST) in REST corresponds to the data transfer between server and client. But the ST corresponds to the state transfer of the client by choosing the choices provided by the server via HATEOAS.

Hypermedia As The Engine Of Application State (A.K.A. HATEOAS)

Hypermedia is an extension of hypertext, which essentially is the text that is composed in a structured format and contains relationships to other objects via links. Hypermedia includes images, video, audio, text, and links to other hypermedia.

Application State, It can be either of

1. The state can correspond to the whole application if you consider the browser as your client. When a user clicks on the profile page link, the browser gets navigated to the Profile page.
2. The state can correspond to individual resource states. An order state can be moved from pending to checkout.

The state of the application on the client should be changed based on the choices provided by the server in the form of the hypermedia links. Clients should be able to navigate through the application by choosing the appropriate hypermedia link.

Who is the client and what is the debate about discoverability?

Developer Discovery :

When a developer discovers the URLs, resources, and supported HTTP method by browsing the documentation and hardcodes it in the client. Then the client will have some predefined knowledge about the APIs provided by the server. For example, in the case of the mobile application, the app developer will hard-code the UI design based on the knowledge of resources beforehand.

Runtime Discovery :

The client itself is able to figure out everything from the response provided by the server with little or no out-of-band information. The client is generic enough to process the information from the response without any hardcoded information on the client side.

Why is there so much controversy around HATEOAS and Runtime Discovery?

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and discover the possible states it can navigate and possible actions it can do. — Roy Fielding

Basically achieving runtime discoverability is the crux of REST and HATEOAS which makes it complete.

In the HTML-based APIs, Runtime discovery is possible as the content is interpreted and rendered by the browser(client). All communication happens through hyperlinks.

• If we want to navigate to the profile page from the home page, it’s just a hyperlink and the action causes a server call which will in turn return a new HTML and will be rendered by the browser.
• If we want to submit a form, all the required details will already be present on the HTML page including required fields, data types, etc.

The client will not have any prior knowledge of resources and their representations beforehand and still process all the information. The browser/HTML client in this case is acting as a generic client that knows how to interpret HTML, including HTML forms, etc.

But in the case of the JSON-based APIs world, the client is a mobile app or a single-page application.

• Most developers do developer discovery and most of the discussion in this space will assume developer discovery.
• Having a generic client which dynamically interprets the resource and its representation of JSON APIs will have a very bad user experience.
• For most client applications this is not even possible as we prefer a specific look and feel for each resource and each specific application state. Eg: for a mobile application, let’s say we want to build a web shop and the client won’t be able to differentiate between User or Order or Item without predefined knowledge of JSON API resources and datatypes.
• Essentially building a browser-like rendering engine for these types of clients is not feasible.

Is this the end of HATEOAS and thus the end of REST? Yes and No.

Yes, because if we hard-code the knowledge about the API into the client, we lose the benefit of HATEOAS. Server-side changes may break the client and If you are not implementing HATEOAS it’s not REST anymore.

No, when the technology evolves our APIs should be in a position to support the generic client without any changes. As long as it is possible, in theory, to build a generic client that offers all capabilities of the API, the API can be called RESTful.

The client will now have the option to choose how generic it wants to be.

• To provide a great user experience but have dynamic URI building.
• To have certain knowledge but not too much hardcoding of URI and business logic.

How can we implement HATEOAS in JSON-based APIs?

The below GET API provides links to all the choices the server provides and also the template for PUT operation.

GET 
http://localhost:8080/departments/1

{
    "id": "1",
    "name": "depart-1",
    "_links": {
        "self": {
            "href": "http://localhost:8080/departments/1"
        },
        "employees": {
            "href": "http://localhost:8080/departments/1/employees?size=5&page=0"
        }
    },
    "_templates": {
        "default": {
            "method": "PUT",
            "properties": [
                {
                    "name": "createdBy",
                    "required": true
                },
                {
                    "name": "employees",
                    "type": "number"
                },
                {
                    "name": "id",
                    "required": true,
                    "type": "text"
                },
                {
                    "name": "name",
                    "required": true,
                    "minLength": 0,
                    "maxLength": 100,
                    "type": "text"
                }
            ]
        }
    }
}

Benefits of HATEOAS

• Obviate the URI composition logic on the client

You might have seen the above table many times. This has become a universal standard now and having a naming standard is good. Just because they are universal, don’t hard-code the template URI in the client. All the URIs should be dynamically taken from the response. If the client has these URI templates hardcoded it defeats the whole purpose of HATEOAS.

• Prevents clients' exposure to business rules

Let’s say you have manager and employee roles, a certain delete privileges are only applicable to the manager. In absence of HATEOAS, we may code this logic on the client side. The business logic has now crept into the client code. These business rules may evolve over time and we want our clients to be independent of the business rules. With HATEOAS, the client just chooses from the choices that the server sends and the business logic will be only handled by the server.

In the debate of the merits and demerits of HATEOAS, the expectation of the client’s dynamic discovery is misplaced. Many-a-times we tend to hard-code the static contract into the client. There are advantages in providing links that help clients navigate through the choices without duplicating portions of server-side business logic.

About Fission Labs — Fission Labs is a family of over 350+ seasoned engineers with product development at heart and years of experience developing custom solutions and pioneering digital transformation across various technology verticals, including AI/ML, Data Engineering, and Cloud solutions.

Our mission is to help our clients achieve a sustainable digital transformation that’s in sync with their business goals. We strive to reach our goals by harnessing innovation and engineering excellence as an instrument to create symphonies between business processes and underlying technologies.