8

There is a scenario, where we have two commercial applications that are so called REST based(java) but not HATEOAS compliant. Development activity is out-sourced to vendor

Development phase of project is done and planning for functional testing.

We preferred in-house technicians for testing phase to perform functional testing but the technicians have no business/domain knowledge of these two applications. Developers knew the purpose of each endpoint referring to a specific database entity.

I learnt that good restful programming is HATEOAS compliant.

HATEOAS allows (representational (state transfer))

One quick advantage is in testing phase where it just need to start from root end point and navigate to different states, which does not require any business/domain knowledge of application, because api end points are self-discoverable.

Public platforms like Facebook does not follow HATEOS compliant Restful service

If HATEOAS is not a pre-condition for RESTful programming, then, it is unclear on the difference between

  • serverside businesslogic mapped to route, say with python decorator(@route('/'))

    &

  • RESTful end points.

1) What are the advantages of HATEOS compliant RESTful service?

2) What does it take for a developer to redesign any application, as HATEOAS compliant? In order to perform functional testing successfully..

Improve this question
1
  • 2
    You've been sold a bill of goods. What most developers regard as REST services are not actually REST services at all; they are merely JSON endpoints.
    – Robert Harvey
    Commented Mar 10, 2019 at 0:01

4 Answers 4

Reset to default
5

What are the advantages of HATEOS compliant RESTful service?

In short: You stay in control of your server side, minimize client knowledge about server internals.

Imagine Amazon giving you a product page with just the product data, no links or forms to buy the item. It would assume, that you will go to a separate service (let's say a shopping cart service) where you will enter the product ids you want. It would be pretty stupid, wouldn't it?

HATEOAS is not just giving you links about stuff, it is about providing the clients with options to fulfill a specific use-case.

Another example: If I would implement a hotel booking application, I wouldn't just give you the data for rooms, reservations, time-slots, as data, I would give you only the data you need to know (so no internals ids and stuff like that), and only the options specifically designed to guide you through a reservation process.

What does it take for a developer to redesign any application, as HATEOAS compliant? In order to perform functional testing successfully..

Change of mindset mostly. Think of your application "endpoints" or "resources" as web-pages directed to humans. What would you show a human, and what options would you give a human to be able to navigate your application? Creating a HATEOAS compliant application interface is exactly like that.

To be honest, that is not as easy as it sounds, there are certainly a few technical things you have to be aware of. Just one point: of course you don't need an AI on the client side, you just have to have typed representations (using proper Media-types, instead of generic ones), which the client does need to know (just like a browser understanding HTML, CSS, PNG, JPG, etc.).

Improve this answer
7
  • 1
    Have you come across any resource as a good start to adapt the mindset of HATEOAS and implement using Python?
    – mohet
    Commented Mar 10, 2019 at 15:09
  • @mohet I'm not a python developer, so unfortunately no.
    – Robert Bräutigam
    Commented Mar 10, 2019 at 16:03
  • Start with some implementation of HATEOAS like HAL. Look for Python libs implementing HAL.
    – Laiv
    Commented Mar 11, 2019 at 14:49
  • @Laiv Word of caution: HAL is insufficient for many reasons. 1. It's not self-descriptive. If you get a HAL document, does it describe a product, a laundry list, a customer? How do you know? 2. It doesn't have forms (or equivalent), only links, which are good but not enough. 3. It separates navigation from the data completely, which makes it awkward. All in all, you can look up ideas from it, but you shouldn't use it as described.
    – Robert Bräutigam
    Commented Mar 11, 2019 at 15:11
  • It doesn't have forms and It's not self-descriptive. HAL resolve it with curies. They are just links to your API scheme. Something relatively easy to have with Java if you implement Swagger. With a Swagger client, you could have the "forms" and the "self-descriptive" API you need. In which way separates data from navigation? I didn't suffer these issues and I have implemented HAL at least a couple of times.
    – Laiv
    Commented Mar 11, 2019 at 16:00
4

There is no advantage to a HATEOS compliant service. The stated goal is to make the api 'discoverable'. However no-one has managed to develop a client with enough AI to be able to interpret the meaning of links provided with a resource.

As to what it takes to make a service compliant, well the spec is very very bare on this question. The normal solution is to add "links" nodes to your json response which provide the urls of related resources and methods.

My view is that REST and HATEOS are clearly designed to be HTML that is read by a human. Not json which is read by a machine. But a human can also read documentation, or download a prewritten client. Adding HATEOS links to your json API merely adds extra data to your calls.

Improve this answer
19
  • 1
    understanding media types doesnt really come into it. sure i understand json, or html, that doesnt mean i know that the 'buy' link purchases a product
    – Ewan
    Commented Mar 10, 2019 at 12:15
  • 2
    unfortunately if you broaden media type to include the schema of the data you send, then changes to the server inevitably change the schema and hence media type. so no client can know your knew media type
    – Ewan
    Commented Mar 10, 2019 at 16:07
  • 1
    perhaps you can tell me what you think I think doscoverablr means and what you think it means?
    – Ewan
    Commented Mar 11, 2019 at 7:04
  • 1
    @RobertBräutigam I contend that Fielding's dissertation is not very clear at all. How many non-trivial apps besides the web browser comply with HATEOAS? If you follow any discussion between Fielding and someone asking a question, it always goes like this (emphasis in "always"): "I get it now! HATEOAS is <thing>". Fielding: "no, you didn't understand my disseration, that's not what I meant at all". Repeat ad infinitum. When nobody understands a spec/dissertation, my opinion is that the dissertation is at fault.
    – Andres F.
    Commented Mar 15, 2019 at 15:26
  • 2
    @RobertBräutigam my argument is clear. The only authoritative source of information on HATEOS does not specify what HATEOS is clearly enough say whether api X is HATEOS compliant
    – Ewan
    Commented Mar 18, 2019 at 9:25
2

The big idea of HATEOAS is that Hypermedia is The Engine Of Application State. A resource declares links that are valid actions in the current state of the resource. That is terribly elegant because REST (Representational State Transfer) follows practically for free: the client does not need to synchronize their state with the server, they just navigate the application state by following links.

Unfortunately, HATEOAS does not meet real-world requirements that developers have for their APIs.

  • HATEOAS effectively requires that links are provided in some form of service description language so that the client can insert appropriate parameters, select a HTTP method, and so on. The HTML <form> element provides one such system.

    However, it turns out that instead of turning clients into service description interpreters, it's often much easier to hard-code the service description into the client. And it's also easier for the server developers to commit to API stability instead of providing a machine-readable service description.

    This isn't necessarily the fault of HATEOAS, this is just the reality of our tooling.

  • HATEOAS potentially requires multiple links to be navigated in order to complete some action, whereas most REST APIs can be “deep-linked” to perform some action in a single request.

  • Potential benefits around discoverability don't matter: the client is implemented once (during which time discoverability could be helpful to the developer) and then runs many times without having to re-discover endpoints.

    There is a remaining discoverability benefit in that a resource only provides links that are valid in the current state. For example, if a resource doesn't exist you won't get a link to delete it. Or if the client doesn't have the necessary permissions, it won't get a link to patch a resource. But the API will have to deal with invalid requests anyway and the rules about valid actions might already be known to the client, so that typical APIs gain very little this way.

Not all HTTP APIs use a RESTful design, and that can actually cause problems (for example, true RESTful design synergizes very well with HTTP caching). In particular, misunderstanding URLs as actions or endpoints leads to a more RPC-ish design. Doing a round of What Would Roy Fielding Do and at least considering a HATEOAS approach can help to use URLs only to represent resources. In many cases, a proper REST design will turn actions/verbs into resources/nouns.

Improve this answer
3
  • Just a note. One important characteristic of the WWW architecture is its long-running stability and resilience. These are the only reasonable arguments to make our services Web. Well, that one and the fact that the WWW reaches almost every single corner on the planet. It reaches many people and it does it with a fair grade of robustness. These are the characteristics you want your service to adopt when it goes Web and it could not if we don't make our services HATEOAS. It's that simple. No HATEOAS means tight coupling server-protocol-client. Tight coupling means no long-run stability.
    – Laiv
    Commented Mar 11, 2019 at 11:11
  • The advantages of HATEOAS, beside discoverability, it could be addressed to many and different clients/consumers as soon as they are HATEOAS interpreters (as any browser and HTTP client could be). If your services are going to be only consumed by your only single app client, then it could be overkill at the early stages of the system. However, if you are meant to reach several and different consumers, no matter their stacks, business and locations dropping HATEOAS from your specifications is huge mistake. If you don't think so, tell me why is Google+ API shutdown causing so many headaches.
    – Laiv
    Commented Mar 11, 2019 at 11:20
  • @Laiv I'm not sure whether I can agree with your assessments. Resilience is a property of the internet at large, but not really of the WWW. The Google+ deprecation would not have benefited from a HATEOAS approach: it's not the style of the interface that causes headaches, but the dependency on the service itself. Some amount of churn can be expected, e.g. that “log in with Google+” had changed to “log in with Google” many years ago.
    – amon
    Commented Mar 11, 2019 at 18:07
2

1) What are the advantages of HATEOS compliant RESTful service?

There are three roles at play here: server, user-agent, and user. Let's take this web application as an example. We make HTTP requests to the "server" and get back HTML/etc responses. The web browser is the "user-agent" that hides the HTTP/HTML/etc complexities from us and provides us afforances like links and forms to interact with. The user-agent is more often referred to as the client. You and I are "users".

One of the things the REST architectural style gives us is the decoupling of client and server. The client in this statement is the user-agent (think web browser). StackExchange can update their site without us needing to update our browser. Browsers can be updated without StackExchange needing to update their servers. As long as the two are speaking the common language of HTTP/HTML/URI/etc, each can evolve independently. This common language is referred to as the Uniform Interface.

In the context of REST APIs, it's not as straightforward which elements play which roles. The server is still the server. The user-agent is usually an HTTP client you use to make HTTP requests to the server. The user is the application. That's a strange thing to say, but it's important to understand the benefits you really get from hypermedia (HATEOAS).

The reason that getting the same evolvability characteristics from APIs as we get with the web is so elusive is because users of the web are humans and users of APIs are programs. Humans can easily adapt to a moved button or a new workflow. Programs have to be updated to deal with most changes.

However, that doesn't mean that hypermedia isn't useful for APIs. Usually, we interact with APIs through HTTP clients. Just like with web browsers, we can choose any HTTP client we want and it will work with any server that speaks HTTP.

One problem with this is that programmers need to be proficient in a dozen or so web standards in order to use the API. So, what we end up doing is creating wrappers around the HTTP stuff making functions that programs can call for doing all the things the API can do. Without hypermedia, those user-agents necessarily have to be coupled to the functionality the server supports. If the server adds a new feature, the user-agent needs to be updated to support that function.

Here is where hypermedia comes to the rescue. If the way your app does state transitions is encoded using hypermedia and included with the resources returned by the server, the client doesn't need to hard code those points of interaction anymore. If your programs interact with the user-agent by following links, adding a new feature to the API doesn't require any changes to the user-agent. It does however require the program (think user) to be updated to make use of the new feature.

Imagine if you had a user-agent that was generic, but felt like it was tailor made for your API. It abstracts all of the technical details of HTTP and media types so it's really easy to use. You can use the same user-agent for multiple APIs. You could even link from one API to another and the user-agent would handle it as smoothly as if it would if it was the same API. This is the kind of thing that's possible with hypermedia.

2) What does it take for a developer to redesign any application, as HATEOAS compliant? In order to perform functional testing successfully.

I use JSON Hyper-Schema to do just that all the time. Hyper-schemas are like templates that you can apply to plain JSON to add links/forms to your JSON. You can use a Link header with rel=describedby on your responses to indicate a hyper-schema to apply to a JSON response. One of the benefits of this approach is that you don't have to change the JSON to add hypermedia. It's completely backwards compatible with any JSON API.

I'll often create a simple proxy server to add hyper-schemas to plain JSON APIs I'm working with. I can then browse those APIs with Jsonary. Jsonary is a user-agent that can create a user interface given a JSON Hyper-Schema API.

Here's an example of a TODO List API running in the Jsonary browser. http://json-browser.s3-website-us-west-1.amazonaws.com/?url=http%3A//hypermedia-todo.herokuapp.com/. It's not the prettiest interface, but you should be able figure out how to use it with no documentation. Just follow the links and fill out the forms.

There are some limitations to adding hyper-schemas to a plain JSON API. Because a hyper-schema is like a template on the JSON, you can only express links for things the JSON has data for. Take paging for example. If I'm on page 4 and I want to provide a next link to page 5, I can only do that if the JSON includes the information that the next page is "5".

Improve this answer
2
  • Any reference to HATEOS based REST programming using GO lang?
    – mohet
    Commented Mar 18, 2019 at 2:28
  • These are architectural level concerns, so it applies the same to any programming language. I suggest you start with choosing a media type (JSON Hyper-Schema, Siren, etc). Then find (or build) a user-agent for that media type. Then build your server such that you can navigate your application using that user-agent. That experience of building your server to work with a general purpose user-agent will be better than any reading material I could give you.
    – Jason Desrosiers
    Commented Mar 18, 2019 at 4:36

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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