This language always bothered me, 'client' in this case surely means a advanced general intelligence, or 'human', who can futz around with the URIs to try and get what they need. Maybe that's better than CORBA, but it's not the Universal Translator of interfaces by a long shot.

Besides a structured data browser for humans, or some kind of transforming proxy, it's hard to see what use cases this is clearly and practically better for.

And if we're going to compare "a REST client" as purely the requestor and not the interpreter of the data to something that does JSON RPC calls or graphql, which is often basically REST+, I'm not sure there's any real difference.

Conversely, an API is not useful without a human or something automated to use it.

The point of REST/HATEOAS is not to have arbitrary random APIs that can be magically discovered by a random magic application. There must be some agreements and standards there.

OData, GData and AtomPub are good examples of APIs that follow HATEOAS, for example.

Is any software useful without someone, you know, using it?

Is doing a lot of work here. Firefox can help me search Google and eBay (and so can lynx and w3m) with "only" a "generic understanding of hypermedia".

Because HATEOAS is basically useless for machines, and industry runs on machines.

It's fine when you've got a human clicking things that they're looking at, but there's no reliable way to reinterpret it for a different use because it's so wildly context sensitive in ways that only humans understand. Meaning of things in HATEOAS may be / is intentionally allowed to be communicated by non-structured text that accompanies the actions, as literally every example in this page shows.

If you're doing anything but rendering it for humans to interpret, that flexibility makes it basically impossible. Or binds you to a single output structure, with no way to structurally verify if changes are relevant or not.

The purpose of HATEOAS seems to be to provide web crawling clients (human or otherwise) visibility of the arbitrary actions/links that a particular endpoint provides in a particular state - but the links are disconnected from their context and intended interaction with the page. HATEOAS doesn't seem to acknowledge that a UI needs to provide context for user actions, or that API integrations are designed up front with full knowledge of the API contract .

It seems to me the only thing HATEOAS is useful for is browsing black and white pages with a bunch of blue and purple links. Or maybe SEO

That said, I don't quite agree with the criticism of out-of-band information. Is the HTML spec not out-of-band information?

Likewise, if they had used an SGML api as the example instead of HTML, would not all the same criticisms of the JSON, for not being HATEOAS, be valid?

There are already many JSON-based APIs on the right path like ActivityPub, JSON-LD, and others. Having to know the specs of these things is no more out-of-band than knowing HTML.

TL;DR: SGML:HTML::JSON:XXXX. If we can all agree on a good XXXX instead of freeforming from just JSON every time, we can get closer to HATEOAS.

It isn't. The HTML spec isn't transferred every time a webpage is accessed, so it's not exactly information. This is like saying "english" is "out-of-band information" when reading a website written in english.

"Out-of-band" has a very precise meaning here, it comes from the telecom term "out-of-band signaling". There's a wikipedia page: https://en.wikipedia.org/wiki/Out-of-band_data

Well yeah, that'd be pretty ugly on most browsers without some kind of stylesheet, but...

> Hence they would need IDs on those DIVs to style and place them.

...this doesn't really follow from that. Like yeah, that's probably a good idea (even better would be some more specific tags than just divs), but the client has everything it needs to present the data to the user even without that.

The point, I think, is that styling is a separate concern; HATEOAS and REST have more to do with structuring information and interactions with it, and the examples therefore emphasize that instead of a possibly-accidental prescription of some specific styling for that information.

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

If in this instance, "REST client" means an application performing actions autonomously, I don't see how this statement could possibly be true. Someone writing a client will need to know how the server is going to return responses to requests. It needs to know what operations the server supports.

It really seems like REST and HATEOAS, using the strictest definitions, really just mean server-side HTML rendering, which is nothing new. I figured we swapped to client-side rendering (And therefore, servers sending XML or JSON, and the client handles putting it into the page) to reduce server-side loads and the cost of increased CPU usage client-side.

My understanding is yes, those are all clients.

> If in this instance, "REST client" means an application performing actions autonomously, I don't see how this statement could possibly be true. Someone writing a client will need to know how the server is going to return responses to requests. It needs to know what operations the server supports.

I think the "generic understanding of hypermedia" is knowing how to follow links, use the HTTP verbs, and interpret the HTTP status codes.

I think the idea is that if you know to query your account balance with "GET /accounts/12345" and it offers something in its response that looks like an HTML web form or json containing a link to "/accounts/12345/deposits", you could easily infer that a "POST /accounts/12345/deposits" would be used to make a deposit.

How would you know what to POST? Look at the web form and emulate that, or just try it and get a specific error about what fields are missing, ideally with a link to docs.

> It really seems like REST and HATEOAS, using the strictest definitions, really just mean server-side HTML rendering, which is nothing new.

That's actually htmx, which makes sense you got that vibe, because it is the htmx blog and they are highlighting a way to self-document the API with web forms, but REST is connected to the HTTP verbs and HATEOAS is connected to the payload to make REST discovery more intuitive.

As far as I know, nobody really uses this stuff, or at least I haven't seen it in production, but it's been a good idea floating out there for at least 10 years now.

If someone made a HATEOAS linter and a Postman extension, in addition to the obvious htmx endorsement, maybe it would gain some traction.

Always thought that it was basically each server generated page providing the list of links/actions that was allowed from then on.

Basically a lazy, incremental, and fine grained API.

The issue being that it might not be very useful since links have to persist in general on the web. (maybe I misunderstand and it's a non issue?) whereas HATEOAS would be useful if links were never shared: then they could be dynamically generated or updated?

Depending on the use agent and what not, the routes through a given server-rendered website can be different, tailored, per request.

> REST purists often complain, for example, that so-called REST APIs aren’t actually REST APIs because they do not use Hypermedia as The Engine of Application State (HATEOAS). Fielding himself has made this criticism. According to him, a real REST API is supposed to allow you to navigate all its endpoints from a base endpoint by following links. If you think that people are actually out there trying to build REST APIs, then this is a glaring omission—HATEOAS really is fundamental to Fielding’s original conception of REST, especially considering that the “state transfer” in “Representational State Transfer” refers to navigating a state machine using hyperlinks between resources (and not, as many people seem to believe, to transferring resource state over the wire).8 But if you imagine that everyone is just building FIOH APIs and advertising them, with a nudge and a wink, as REST APIs, or slightly more honestly as “RESTful” APIs, then of course HATEOAS is unimportant.

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. 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.

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

Sure, 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

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?

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.

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.

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.

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?

The API here is HTML + HTTP. That's it, that's the API. In a browser, the Hacker News website/HTML is not the API.

"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's not something that was "promised" by REST. Quite the opposite, REST is about applications not needing to know the structure that's on the other side, only the format and how to navigate it.

"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 software but don't really match its model or intent.

Perhaps you're expecting hypermedia to replace something else? You're mentioning "WSDL, OpenAPI and friends". Well, those are perfectly fine, but they're orthogonal to REST and hypermedia.

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.

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.

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.

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.

Nope. But people like to trot the term out to sound fancy and smart. Anyone wasting their time implementing this is doing some serious yak shaving.

HATEOAS is not magic. It's not about having arbitrary JSON APIs that can be magically understood by clients. It's just about formats that support linking between resources in a standardized manner (like HTML), among other things, that's it.

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.

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.

> 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...

> 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?

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

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

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.

> 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

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.

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.

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. Kinda sucks that an entire industry misled you into thinking otherwise, but that is its wont...

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. This is an app based on the REST architectural style.

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.

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 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.

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

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).

> <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.

Can also do a nice trick of rendering nicely formatted json objects in html with proper links if a browser is requesting html/text. For an extra bonus split the page and render the docs right next to it, too. If application/json is requested, return just json to be consumed by programmatic clients.

That said, while it was really nice to learn and navigate the API from the browser that way, none of the programmatic clients ever used the "auto-discovery" feature. They jumped right to the resource the needed and didn't bother with the links.

At this point REST is just whatever most popular companies designed and called "REST-ful" is what REST-ful became. As much as Roy wants to claim it's not "pure" enough, the ship has sailed so speak.

Taking the example from the article... if you want to present bank account information to a user and allow them to take actions on it, then focusing on HTML (and CSS) is a great idea.

However, the data is going to be stored somewhere, and you're going to want to retrieve it and transform it into the desired presentation HTML for your app. In the case of the article, you could say describe these two operations abstractly like this:

    retrieveAccountInfo(dataSource) -> (accNo, balance, status)
    presentAccount(accNo, balance, status) -> HTML

    presentAccount(retrieveAccountInfo(dataSource))

presentAccount is just as logically coupled to retrieveAccountInfo in the "hypermedia" case as it is in the "rest", and possibly somewhat more coupled in terms of infrastructure, depending on what's going on at the application server. The application state is determined in exactly the same way.

Of course, there are tradeoffs between running application code server side vs client side. But it really has nothing to do with hateoas and decoupling, and the article doesn't touch on it. (One of the big advantages to running the app server-side is that there's no need for client-side javascript -- this makes the htmx approach -- where the app runs server side but you also need client-side javascript -- a bit questionable, IMO.)

JSON isn't a great HTMl representation, and the wikipedia examples are definitely missing details about how the underlying API is used. But extremely simple HTML just feels worse.

Both pages use a bank account as the example, but my actual bank account has dozens of actions available and is certainly modeled in a way that wouldn't be intuitive for people. Which means we've got an example that isn't easily parseable by computers, because we have mixed labels and data in the HTML, and isn't useful for human beings due to how complex real world entities are.

I genuinely can't tell if this is like monads (which are useful, but often poorly explained) or if this is just a bad idea.

I see a lot of people saying "HATEOAS doesn't work/has anyone ever used it".

The answer is YES: the world wide web and any traditional web 1.0 application uses it quite successfully. The important thing to realize is that an HTML-based web server is providing an API: a hypermedia-based API. It is providing it to a hypermedia client, namely the browser.

The concept has not mapped well to JSON-based data APIs because those APIs are not typically consumed by REST-ful clients. Or, if they are as in an SPA, the hypermedia functionality of the client is ignored in favor of a thick-client approach.

We have written a book on the idea of a hypermedia system that explains this in far more detail:

https://hypermedia.systems

which stresses the systemic nature of hypermedia when building a distributed application.