5 ms·

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 inter

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 https://de.wikipedia.org/wiki/Naked_Objects

ZeroGravitas 3y ago
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/ 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?
whstl 3y ago
"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.
- danbruc 3y ago
  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.
  - whstl 3y ago
    > "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.
natural219 3y ago
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 https://guides.rubyonrails.org/routing.html
ramesh31 3y ago
[flagged]
- whstl 3y ago
  That's false. The browseable web itself uses hypermedia. And there are formats that use it successfully, like OData, GData and ActivityPub. 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.
napoleongl 3y ago
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-extensions/index.html https://docs.shareaspace.com/v1-8/developer/external-extensi...
lolinder 3y ago
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.
- danbruc 3y ago
  In that case your REST API is just a new name for web application and your API responses are just web pages.
  - lolinder 3y ago
    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
    - rewmie 3y ago
      > 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.
      - myk9001 3y ago
        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.
39Wc 3y ago
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 https://github.com/apache/causeway [2] https://github.com/lagoshny/ngx-hateoas-client https://github.com/lagoshny/ngx-hateoas-client
ivan_gammel 3y ago
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.
dragonwriter 3y ago
> 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).
lucideer 3y ago
> 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.
pharaohgeek 3y ago
I believe that Apple's AppStore Connect API uses HATEOAS. That's pretty non-trivial.

ZeroGravitas 3y ago

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

whstl 3y ago

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

danbruc 3y ago
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.
- whstl 3y ago
  > "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.

natural219 3y ago

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 https://guides.rubyonrails.org/routing.html

ramesh31 3y ago

[flagged]

whstl 3y ago
That's false. The browseable web itself uses hypermedia. And there are formats that use it successfully, like OData, GData and ActivityPub. 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.

napoleongl 3y ago

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-extensions/index.html https://docs.shareaspace.com/v1-8/developer/external-extensi...

lolinder 3y ago

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.

danbruc 3y ago
In that case your REST API is just a new name for web application and your API responses are just web pages.
- lolinder 3y ago
  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
  - rewmie 3y ago
    > 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.
    - myk9001 3y ago
      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.

39Wc 3y ago

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 https://github.com/apache/causeway [2] https://github.com/lagoshny/ngx-hateoas-client https://github.com/lagoshny/ngx-hateoas-client

ivan_gammel 3y ago

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.

dragonwriter 3y ago

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

lucideer 3y ago

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

pharaohgeek 3y ago

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