Hacker News Reader

Comment by danbruc | Hacker News Reader

Seriously, has anyone ever made a non-toy implementation conforming to the idea of HATEOAS?

A REST client needs little to no prior knowledge about how to interact with an application or server beyond a generic understanding of hypermedia.

Nothing but a generic understanding of hypermedia? You need some substantial understanding of language and the world to figure out where this link will take you.

<a href="/accounts/12345/close-requests">close-requests</a>

Sure, English is not my first language and financial terms are probably a real weak spot, but I have at best a vague idea what this will do. Can I request to close my account? But why would I need requests for that, plural? So maybe it is not about closing my account but instead a close request is some financial term? If it is, I still have no idea what it is good for.

For consumption by humans, developers poking around in a new API, HATEOAS might be nice. But how on earth are you going to write software that can consume such an API, dynamically discover, understand and use available operations? Maybe you could use ChatGPT to do this. And how are you going to build an UI for this that is any better than what naked objects [1] can deliver if you do not even know which operations the API has to offer?

[1] https://de.wikipedia.org/wiki/Naked_Objects

View on HN

> You need some substantial understanding of language and the world to figure out where this link will take you.

> <a href="/accounts/12345/close-requests">close-requests</a>

There's two types of understanding here: a technical understanding of hypermedia behaviours, and a contextual understanding of application domain intents. A hypermedia client doesn't need to understand the latter at all: it only needs the former to be able to present a user with direct context (whether the user can then understand what to do is mostly up to the application designers, but it's outside of the responsibility of the hypermedia client - it's just the messenger here).

For example: this is a HTML anchor element (presumably the client has been served a Content-Type: text/html header here to inform it of that) - HTML anchors initiate GET requests to an associated href. In this case the href starts with a / indicating that it is relative to the serving origin. That's the beginning and end of so the hypermedia client needs to know: all self contained, no out-of-band knowledge required.

Any further confusion suffered by the user related to financial or English language knowledge is up to domain knowledge of the application and not within the bounds of what HATEOAS does.

If you read the article, it's pretty clear that they're not advocating using HATEOAS for a computer-consumable API—it's all HTML, meant to be rendered by a web browser and clicked on by the user. You could code a computer agent against this as well, but a hypermedia system is designed for users first.

In that case your REST API is just a new name for web application and your API responses are just web pages.

Yes, exactly. The confusion (not unique on your part) comes from the notion that REST has something to do with the JSON/XML APIs that the term conjures up in your mind. Whoever said that's what it was supposed to mean? (Lots of people, I know. The point is, they're wrong.) REST is just how the Web works (or at least worked—at the time that Fielding wrote his dissertation).

jcrites explains it really well: <https://news.ycombinator.com/item?id=23672561>

The answer to your question, "has anyone ever made a non-toy implementation conforming to the idea of HATEOAS?", therefore, is "Yeah. Your Web browser."

Disabuse yourself of anything you have ever been told that has led you to believe REST is an alternative to (or a special flavor of) RPC. It's not about RPC.

Then I will have to read the thesis once more. Sigh. I am pretty sure it talks about APIs, that is interfaces consumable by software. What a browser does, formatting and rendering a response, is not what I would call consuming an API. Well, the browser is actually consuming an API, it sends URLs and receives HTML or whatever. Is that the API the thesis has in mind, HTTP itself, while I was always thinking about the one on top, the one that lets me transfer money from my account to someone else? In some ways that would make sense, in others not at all.

> "Is that the API the thesis has in mind, HTTP itself, while I was always thinking about the one on top, the one that lets me transfer money from my account to someone else?"

Yep, that's it.

Field's REST/HATEOAS can be used as a "layer" underneath a more traditional, schema-bound, RPC-like API. This is what Google did with GData, for example.

I don’t think that is a good explanation.

> REST is about describing services that you can interact with with no prior knowledge. REST is about completely decoupling the client and server (in terms of prior knowledge) beyond standardized media types (HTML, CSS, JS)

The idea that REST is confined to standard media types like HTML and CSS is wrong. It is sufficient that media types are known to specific clients and server, but that does not have to include web browsers or arbitrary clients.

Quote [1]:

REST provides a hybrid of all three options by focusing on a shared understanding of data types with metadata, but limiting the scope of what is revealed to a standardized interface. REST components communicate by transferring a representation of a resource in a format matching one of an evolving set of standard data types, selected dynamically based on the capabilities or desires of the recipient and the nature of the resource. Whether the representation is in the same format as the raw source, or is derived from the source, remains hidden behind the interface. The benefits of the mobile object style are approximated by sending a representation that consists of instructions in the standard data format of an encapsulated rendering engine (e.g., Java [45]).

[1] https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...

I don't get what your quibble is.

> The idea that REST is confined to standard media types[...] is wrong

You sourced the response yourself:

> REST components communicate by transferring a representation of a resource in a format matching one of an evolving set of standard data types

... and given that you did just copy and paste that part, it leads me to believe that that's not what you've got an issue with. So what do you have an issue with?

„Standard media type” has different meaning in the comment you refer to and in the quote.

This is not a very helpful response.

You reference a comment that basically says that REST is HTML UI talking to server via links and forms, rather than interaction with JSON or XML-based API. This is not correct, neither according to original dissertation nor according to modern understanding of RMM 3 APIs. API using JSON can support HATEOAS. Standard media type in the sense of REST is not the W3C media type, but anything that both server and client can understand. appilcation/hal+json is a good example.

Nope. Try again. It "basically" says what it says—which is the same thing that the part you quoted from Fielding says—and nowhere does it say that the media type has to be HTML, which is what you (now) seem to be implying (but are unable or unwilling to articulate for some reason).

How exactly do you understand the following quote that is part of what you call a „good explanation“?

> REST is about completely decoupling the client and server (in terms of prior knowledge) beyond standardized media types (HTML, CSS, JS)

I understand it the way it's written. I don't know what you're looking for here; jcrites is not staying that { HTML, CSS, JS } are prerequisites to REST. They're giving examples of standard media types. If there are other media types for which it is possible to do REST, then those are acceptable, too, of course. But HTML is not a requirement.

The comment you're complaining about says "beyond standardized media types (HTML, CSS, JS)".

"Beyond" in this case means "not only".

You're absolutely correct in stating REST is not confined to HTML, CSS, JS. A JSON, XML, or binary-based media type are all compatible with the architectural style.

I don't think the grandparent implies otherwise, though. They are using the browser/HTML example to describe the particular mechanics of client/server interaction, which are key to a REST application.

They also bring up "decoupling the client and server (in terms of prior knowledge)". As far as I understand, this isn't about an ability of an arbitrary client to talk to the server.

This is, again, easier to explain using the web browser as an example, but the principle equally applies to any client. Think of a "traditional" web application (Django, RoR, etc).

Say, one day you decide to completely rewrite it -- add new pages, remove some existing pages, change the site structure (as in which pages the user can navigate to from a given page). While the app has changed beyond recognition, the user doesn't need to download a new version of browser, they can still point their existing browser to the app's home page and it will just work.

Now, all of the above should hold for a RESTful app based on a binary media type. I believe, this is the key point of going REST-way.

There's a trade-off, of course. While the client is decoupled from the server along one axis, they are fundamentally coupled along another. Imagine a RESTful banking app, and let's say we would like to add a list of recent transactions to the home screen of a mobile client, but the server resource representing the home screen doesn't encode this list in any way. Well, there's is no way to just add it on the client in this case, at least without breaking the principles of REST hence defying the whole purpose of choosing this architectural style in the first place. We have to change the backend code in this case.

I can readily see how the limitation described above might be a deal-breaker for a lot of apps as we know them today.

Yes, that's essentially their point—REST started as a description of a good hypertext architecture and was coopted to describe just about any JSON API. HATEOAS only makes sense in the original context.

> In the early 2000s the concept of REST was appropriated from its initial conceptual environment as a description of the early web into other areas of web development

> Yes, that's essentially their point—REST started as a description of a good hypertext architecture and was coopted to describe just about any JSON API. HATEOAS only makes sense in the original context.

I don't think that your opinion is valid. What you refer as "JSON API" is actually just resources being represented with a specific JSON-based media type, in the same way that opening a page is actually a resource represented as a HTML-based media type. Some web scrapers are basically HATEOAS clients.

I believe the grandparent is making a valid point. It depends on implicit assumptions we have in mind reading it.

The way I'm reading your comment, that JSON-based (or XML-based, or some binary format-based for that matter) media type encodes hyperlinks in some form. Then the client is a simplified, specialized browser, if you will. But the mechanics of client/server interaction are essentially the same as a "traditional" web application (as in Django, RoR, PHP, etc).

And if it's a machine-to-machine interaction, the client is very simalar to a web crawler/scraper, although the media types it parses is not necessary HTML.

In other words, you are absolutely right in that REST is non confined to HTML.

What the grandparent means by JSON API, I think, is the kind of HTTP API we are used to see designed for mobile and SPA clients -- pretty URIs for endpoints, HTTP methods, JSON-serialized request/response bodies...

Those can actually be very nice API, pleasant to work with. It's just that it's not REST.

But at this point, it's probably more productive to go with the flow and just accept people refer to such API as REST.

That said, to me, understanding the difference is still valuable. Even if I'm not going to mention it out loud in a work setting.

In that case what's the point of any of it? The user doesn't care about how your URLs are structured. They just read pages and click links, and anything below that is up to the programmer's preference

> The user doesn't care about how your URLs are structured.

This sounds like you're still thinking that REST is supposed to mean what you thought it meant before (and that it somehow has something to do with "how your URLs are structured").

I'm struggling to glean any meaning out of multiple explanations of HATEOAS beyond "response bodies with hyperlinks in them". Whatever it is, it's too unstructured for computers to automatically use, and unnecessary for humans, who are quite capable of using, well, any website designed for a human

The phrase "hypermedia as the engine of application state" is something Fielding came up with when philosophizing about the architectural style of the Web circa 2000 and how it differed from other architectural styles. That's all it is. That it's "too unstructured for computers to automatically use" is not a failure case, because there was no objective other than to describe how the Web worked. He was developing a taxonomy—to guide how things should (continue to) work based on the world as it already is—not trying to invent something new and admonish people that "Hey, this is how we really ought to be doing things"—unlike the tone of many articles that you've probably read about the promises of this whole "REST" thing, right?

If you expect it to be anything else at this point, then you are sure to end up disappointed, because you are setting yourself up for failure by thinking that it's something that it's not. Kinda sucks that an entire industry misled you into thinking otherwise, but that is its wont...

Think of a "traditional" web application (Django, RoR, etc).

Now, if instead of such a web application we have one based on a binary media type instead of HTML and a custom client instead of the browser, but otherwise everything described above still apply, this is a RESTful app too.

If a decoupling like this is a priority for an app, REST is a good choice for it.

We have to change the backend code any time we want to change what's available on one of client screen's and where the user can navigate from that screen. This can be a deal-breaker limitation for a lot of apps. They're better off designed around another architectural style -- an API having pretty URIs for endpoints, JSON-serialized request/response bodies, utilizing HTTP method for CRUD operations is one such alternative.

> Whatever it is, it's too unstructured for computers to automatically use, and unnecessary for humans, who are quite capable of using, well, any website designed for a human

Another person posted a good answer to this part of your comment. But let me respond to it too.

"any website designed for a human" is an instance of REST/HATEOAS architecture by definition. Roy Fielding came up with the name to describe software systems organized exactly like this.

> it's too unstructured for computers to automatically use

Indeed. In my opinion, designing an app meant for automatic consumption by a computer in RESTful style is not a great idea.

[Ed: correct] Caching.

Humans can just as easily read an OpenApi spec.

"Seriously, has anyone ever made a non-toy implementation conforming to the idea of HATEOAS?"

Yep, your web browser uses hypermedia. But if you want something that is an API, then there is OData, GData and AtomPub all follow HATEOAS.

My browser has no idea how to interact with a proper HATEOAS conforming REST API, I would be doing that, the browser would just show me responses. And if one claims that this is all that is necessary, because the API response already contains some HTML form for me to interact with, then you have done nothing but relabeled web applications as REST APIs and API responses are just a web pages.

How do you consume an OData API without baking the structure of it into your code in one way or another? And just rendering generic list and detail views does not count, I think, that will most likely not provide any good user experience.

> "My browser has no idea how to interact with a proper HATEOAS conforming REST API"

Here's the thing: HTML via HTTP _is_ "proper HATEOAS conforming REST API", as far as was described by Roy Fielding. It follows the principles of REST, as it was the basis for the whole thing including REST.

> "How do you consume an OData API without baking the structure of it into your code in one way or another"

You need to know about OData to consume OData. HATEOAS is not about magic, it is about consuming formats that conform to a specification, such as HTML, OData, GData, AtomPub.

The resources are flexible and arbitrary, or can be generated at runtime. The format is not. It is previously agreed by client and server.

> "And just rendering generic list and detail views does not count, I think, that will most likely not provide any good user experience"

Well, HTML can do it. Some websites I use definitely have good user experience.

OData was very useful for me to expose databases to Excel users, and the user experience was alright according to these users.

If you're looking for something else, maybe there's some example out there. Is Gemini, or perhaps Gopher, compatible with HATEOAS? Maybe, I don't know. But if you're looking for "magic APIs", there's none. No magic was ever promised. Nor was "good user experience". REST is just an architectural pattern based on how HTML/HTTP work on the browser.

If you really want, perhaps you can always extend OData into another format to determine how forms, lists, confirmation dialogs, etc, will be rendered by a client. Heck, you could even send styling information. At this point you'll probably be reinventing part of HTML, though.

Let's take a weather database. I point my browser to some URL, you send back some HTML that the browser shows to me. In order to get a nice, uniform architecture you have followed all the REST principles and I can click around in the database. Fine, you build a nice web application following REST principles.

What you did not do is build an REST API. API means consumable by software and just formatting and rendering the response does not count as consumption by software, at least in my book. I want to get the data and compute some statistics on it. For that I need to know the structure of the data in advance, need to know which URLs to retrieve, which operations to perform, which data structures to expect. That is what WSDL, OpenAPI and friends are for. That I can understand XML, JSON or OData is not good enough.

But if you do not make the structure of the API explicit somewhere and only tell me what I get and where I can go next while I am interacting with the API, what can I do except baking the structure into my code in one way or another? HATEOAS and API just do not work together. So what am I still not getting?

> "What you did not do is build an REST API"

The API here is HTML + HTTP. That's it. A website is, as far as the API is concerned, just the content.

> "I want to get the data and compute some statistics on it. For that I need to know the structure of the data in advance, need to know which URLs to retrieve, which operations to perform, which data structures to expect"

Not needing to know the structure to automate usage of the content is not something that was exactly "promised" by REST. REST/HATEOAS is only about having standardized formats to display the hypermedia, make it discoverable within constraints (a browser for HTTP/HTML, a database program for OData, etc).

Even with websites, I might need previous knowledge to know where to navigate to, which URLs to access. When I come to Hacker News, I always click on "threads" at the top to see if anyone replied me. This is often discovered thanks to hypermedia (in this case a link). But in my case someone had to point it out to me (this is analogous to documentation).

> "So what am I still not getting?"

My assumption, but since you asked: I think you're expecting the original REST paper and hypermedia to be something that it isn't, and to apply to things it isn't supposed to. You're trying to apply it to arbitrary APIs that are supposed to be consumed exclusively by custom software. This doesn't really match its model or intent.

HTTP/HTML content is consumed by browsers. OData content is consumed by Excel, Access etc. AtomPub content is consumed by publishing/blogging/etc software. GData is a fun one: it is (was?) used as a foundation of traditional API clients.

Another assumption, but perhaps you're expecting hypermedia to replace something else? You're mentioning "WSDL, OpenAPI and friends". Well, those are perfectly fine, and they're orthogonal to REST and hypermedia. GData is a good example: Google APIs used GData as a foundation, but actually needed extra documentation and extra code on top to drive users to the correct endpoints.

The "discoverable" advantage of hypermedia APIs does not mean that applications should be intelligent and discover how to use the API just by accessing it. This is possible, don't get me wrong, but there will be massive constraints: either you build HTML/CSS/JS to allow arbitrary apps, or you have a simple tables app that consumes ODAta. If you want a fancy iPhone app, you'll have to start hardcoding a lot of assumptions into the app.

The H of HATEOAS means hypermedia, a term created by Ted Nelson in the 60s. It's related to hypertext, which is the HT of HTML and HTTP. HATEOAS/REST is about creating hypermedia APIs, including HTML/HTTP. This means rich context, like Wikipedia, a database, or a Website.

Not everything matches this. The app I work on doesn't. And that's completely fine.

Excellent points.

As for:

> My assumption, but since you asked: I think you're expecting the original REST paper and hypermedia to be something that it isn't, and to apply to things it isn't supposed to. You're trying to apply it to arbitrary APIs that are supposed to be consumed exclusively by custom software.

I just want to point out that Fielding in his thesis details many different types of architectures. His focus is on REST and hypermedia - and especially how it fits well with efficient and correct caching.

But he talks about movable code (java applets, or essentially also modern JavaScript applications like those built around React), RPC etc.

I think the thesis remains relevant exactly because it's not only about REST.

Yep, I think that's a very important point. Not every API has to conform to Fielding's view of REST or to have hypermedia/HATEOAS.

Okay, I guess now the pieces are falling into place, the same conclusion just occurred to me in a different part of the thread, HTTP is the REST API and not an API build on top of HTTP. I will read some things again with that in mind, but currently my primary thought is how confusingly HATEOAS seems to be explained everywhere. If I see the bank account example where I can inspect account balances and make transfers, I of course assume we are talking about some banking API and it never occurred to me in all the years that we are actually talking about HTTP. After all, when I have to implement or consume an API, it will be the banking API, not HTTP. If I write or consume some SOAP service, there is an existing SOAP implementation on top of which I work but I rarely think of SOAP itself as an API, even though it of course is.

Yes.

The goal of the paper is to define clients that are 100% decoupled from the applications being served by some server. The browser is of course the best example of that. The only "shared knowledge" is in HTTP and in the format (HTML, OData, AtomPub). Excel consuming arbitrary OData is another example, Excel only knows HTTP and OData, and it's able to consume arbitrary data sources.

If you want to have, say, a more user-friendly iPhone banking app, that's probably not gonna be an hypermedia app, it's just a regular application that's specific to your bank. This is not decoupled! Which is 100% fine, especially for user friendliness. For this you can start hardcoding URLs and baking in some assumptions, customizing some screens in the app. All of that is fine, but it's beyond the scope of "pure" hypermedia. Which is fine.

> What you did not do is build an REST API. API means consumable by software and just formatting and rendering the response does not count as consumption by software, at least in my book. I want to get the data and compute some statistics on it. For that I need to know the structure of the data in advance, need to know which URLs to retrieve, which operations to perform, which data structures to expect. That is what WSDL, OpenAPI and friends are for. That I can understand XML, JSON or OData is not good enough.

I think you have some degree of confusion on what REST is in general, and HATEOAs in particular.

"Which URLs to retrieve" is provided by the hypermedia format you requested for a particular resource. There are many HATEOAS-based specifications for formats. Your client asks for the ones it supports when sending a request,and the server delivers one based on your request and what it supports.

"Which operations to perform" is also specified as part of the hypermedia format you requested. Your format specifies link relationships valid for a resource according to it's current state.

"Which data structure to expect" makes no sense and is a reflection of the degree of confusion you're in. Your client is responsible for specifying which media type it can consume. The "data structure to expect" is specified as part of the media type. If your client expects specific data structures, it needs to support specific media types that represents them. These media types are not application/json or application/xml. They are media types designed to reflect the format used to express your resource.

> what can I do except baking the structure into my code in one way or another?

You're missing the whole point. With REST, the "structure" that you "bake into your code" is not the URLs, operations, or data formats. You only need a single root resource as the entry point, and that resource expresses all link relations that you need to navigate towards your resource. The link relations provided by the resource already specify which other resources are available to your client, which also includes operations they currently support. Your client also has the responsibility of requesting the resources it wants expressed in the format it supports, which included the data format. I mean, if you write a Atom client you don't request application/xml. Instead, you request application/atom+xml.

If you need an analogy to understand the whole point, check how you navigate HackerNews with a browser. You open a resource representing the main page, and you're presented with a list of resources which include a collection of submissions, links to other collections reflecting specific queries such as new discussions, links to resources that allow you to login/logout or represent your user account. From that initial resource, you use the links provided in it to request other resources. If your current application state supports logging in, there will be a link to that. If your state is already logged in, there will be resources made available only in that state such as your account or logging out. If you opt to request a resource representing a submission, you'll get the submission text and/or link, along with comments. Each comment provides links to other resources such as individual comments, etc.

That's basically the whole point of REST. Do you hardcode references to each discussion or comment? No. you get them through links provided by other resources. Do you always get access to the resource representing your user account? No, that depends on the application state. Etc etc etc.

I think their response would be something like: If you want that kind of data API then look at GraphQL which was designed to do that, not some misuse of REST which was designed to do the things they are talking about.

https://htmx.org/essays/hypermedia-apis-vs-data-apis/

edit to add key part:

> The crux point of this short essay is this: API churn is fine in a hypermedia system because the messages in a hypermedia system are self-describing. We can thrash the API around and the application doesn’t break: human users simply see the new hypermedia (HTML) and select what actions they want to do.

> Humans, compared with computers, are good at deciding what to do and are reasonably OK with change.

> This is in contrast with data APIs. Data APIs cannot be modified without breaking client code and thus must be much more disciplined in their changes. Data APIs also face pressure to provide higher levels of expressiveness so that they can satisfy more client needs without modification.

> This latter situation is especially dangerous when these data APIs are consumed in a browser, because any data-api expressiveness available to a front-end developer is also available to a potentially hostile user, who can fire up a console and begin hammering away at the API. Apparently, facebook uses a whitelist to deal with this.

> Do you?

> Seriously, has anyone ever made a non-toy implementation conforming to the idea of HATEOAS?

Yes, the Web.

> Nothing but a generic understanding of hypermedia?

To understand basic structure and how to determine if you have the ability to do more; actually deep interaction requires knowledge of specific media types as well.

> But how on earth are you going to write software that can consume such an API, dynamically discover, understand and use available operations?

The basic software handles generic hypermedia, and there are modules to handle particular media types and interact with them. The meat solving a problem with REST is defining resource representations (on the service side), and then building handlers that do what you need with those resource types (on the client side).

I have been developing HATEOAS clients and servers for a while. The key to understanding of HATEOAS is that it is not about browsers or arbitrary clients, it is about abstraction. Client and server share the knowledge of the protocol, the data formats, logical names of links and semantics of operations with those links. Client does not need to maintain the complete state and complex business logic for that state, because it can derive the complete state and possible transitions from each server response. If some link is present in response, operation is possible, otherwise it is not. If link with given name exists and semantics imply GET, PATCH or POST, then make this request to this link. No constraint checks, no access management on client, just follow what server tells you. If server allows to cache resource, do it, but don’t forget to do HEAD.

Apache Causeway [1] generates a RESTful API that is HATEOAS compliant, and exists in parallel to the built-in viewer that is based on Wicket.

There are a few HATEOAS client projects out there, such as [2], that will generate a UI from such a (Restful) API. As far as I know it works quite well, but of course it's a bit rough on the edges.

One interesting observation is that the Wicket UI generated by Causeway does not itself use the RESTful API, but it uses the same meta model that is also used to generate the API.

[1] https://github.com/apache/causeway [2] https://github.com/lagoshny/ngx-hateoas-client

We are using ShareASpace for some things at work and they claim to use HATEOAS. Not sure where to link to prove it though… https://docs.shareaspace.com/v1-8/developer/external-extensi...

I believe that Apple's AppStore Connect API uses HATEOAS. That's pretty non-trivial.

I mean, you kinda answered the question there yourself. The whole REST paradigm (spearheaded by the Ruby on Rails community) was strongly influenced and modeled after the HATEOAS paper and ideas. There's some talks and papers about it but I'd have to dig them up, but basically the working reference implementation that shaped the web for years is here: https://guides.rubyonrails.org/routing.html

Reply on news.ycombinator.com