[HN Gopher] HATEOAS: Hypermedia as the Engine of Application State
___________________________________________________________________
HATEOAS: Hypermedia as the Engine of Application State
Author : carride
Score : 52 points
Date : 2023-07-31 16:03 UTC (1 days ago)
(HTM) web link (htmx.org)
(TXT) w3m dump (htmx.org)
| aatd86 wrote:
| Is it me who does not understand what HATEOAS is?
|
| 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?
| mkl95 wrote:
| HATEOS consists mostly of linking responses ("resources") to
| each other, as opposed to nesting data. So instead of looking
| at some nested data, you will follow a link to that data, and
| so on. You probably won't see it in the wild too often, because
| RPC rules the world.
| zamalek wrote:
| Wasn't that the premise of OData? It was
| Atom(RSS)+hyperlinks.
| whstl wrote:
| Yes, OData is a good example of hypermedia/HATEOAS API.
| chromanoid wrote:
| I think the idea is to provide your API as some part of the
| consumer internet. The problem is that a bunch of websites
| tends to be hard to be navigated meaningfully by a machine,
| since the machine must be able to process the moving parts in
| way they do not loose meaning. The idea is that you can simply
| change a link in a result to be able to split your API in an
| API that is served by multiple endpoints (e.g. microservices)
| etc.
| rdtsc wrote:
| I've done the HATEOAS thing as much as possible. Links were
| rendered in json like the site claims not to do. There is json-
| ld, of course, but that was just too much, so I didn't bother.
|
| 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.
| benzible wrote:
| Worth reading this:
| https://twobithistory.org/2020/06/28/rest.html
|
| > 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 [author's acronym for "Fuck It, Overload
| HTTP"] 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.
| thom wrote:
| It's possible that in the age of LLMs this stops being a silly
| idea, but let's not pretend it hasn't up until now been a very
| silly idea.
| phpnode wrote:
| It's a brilliant and beautiful idea that has approximately zero
| success stories in the real world
| Sohcahtoa82 wrote:
| From what I understand, Web 1.0 was essentially HATEOAS.
| schnable wrote:
| The World Wide Web is a smashing success of HATEOS and REST,
| properly understood.
| phpnode wrote:
| Almost all discourse around HATEOAS is in the context of
| APIs
| bertylicious wrote:
| What I don't get about these examples is how the HTML from the
| responses should actually be rendered. I assume no frontend would
| want to render the HTML as is. Hence they would need IDs on those
| DIVs to style and place them. But wouldn't that require out of
| band information too?
| Apreche wrote:
| I agree with the fundamental principle that "true" HATEOAS is
| desirable, and that HTML provides it while JSON doesn't.
|
| 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.
| whstl wrote:
| _" Is the HTML spec not out-of-band information?"_
|
| It isn't. The HTML spec isn't transferred every time a webpage
| is accessed, so it's not exactly information. Also not really
| helpful, it's 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
| schnable wrote:
| JSON is fine too, if it carries the same semantic information.
| Sohcahtoa82 wrote:
| Articles talking about "REST" and "HATEOAS" really need to define
| "client". Do they mean a person? Do they mean a web browser? Do
| they mean an application performing actions autonomously?
|
| > 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.
| throwing_away wrote:
| > Articles talking about "REST" and "HATEOAS" really need to
| define "client". Do they mean a person? Do they mean a web
| browser? Do they mean an application performing actions
| autonomously?
|
| 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.
| 3cats-in-a-coat wrote:
| The theory behind HATEOAS was bullshit until LLMs made smart
| clients plausible. But LLMs don't need HATEOAS to discover an
| API. So turns out HATEOAS is still bullshit.
| jmull wrote:
| I think this article is focusing a lot of attention on a rather
| arbitrary aspect of web apps, and suggesting some bad
| conclusions.
|
| 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
|
| so the page HTML is determined like this:
| presentAccount(retrieveAccountInfo(dataSource))
|
| In the "hypermedia" option from the article these two operations
| run server side in an unspecified way, while for the "rest"
| option retrieveAccountInfo is implemented as at HTTP GET
| returning JSON and presentAccount runs in the browser.
|
| 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.)
| ivan_gammel wrote:
| This article makes a mistake calling RMM0-2 APIs ,,JSON APIs".
| JSON is data format just like HTML, XML or protocol buffers and
| it can be used both by true REST or RPC APIs. Focus on JSON is
| indeed what makes this article ineligible for Wikipedia, it's
| just the wrong angle to look at the subject.
| Groxx wrote:
| > _While attempts have been made to impose more elaborate
| hypermedia controls on JSON APIs, broadly the industry has
| rejected this approach in favor of simpler RPC-style APIs that
| forego HATEOAS and other elements of the REST-ful architecture._
|
| 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.
| _glass wrote:
| One point is that you should develop versioning with HATEOAS,
| instead of putting an ugly /v1/ into the URL.
| taberiand wrote:
| I think it's also basically useless for user interfaces.
|
| 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
| ivan_gammel wrote:
| HATEOAS is perfect for SPAs with server-side persistence
| because it allows to reduce complexity of the frontend and to
| avoid implementing things like security checks twice.
| danbruc wrote:
| 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
| 39Wc wrote:
| 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
| ramesh31 wrote:
| >Seriously, has anyone ever made a non-toy implementation
| conforming to the idea of HATEOAS?
|
| 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.
| whstl wrote:
| 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 wrote:
| 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...
| ZeroGravitas wrote:
| 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?
| lolinder wrote:
| 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 wrote:
| In that case your REST API is just a new name for web
| application and your API responses are just web pages.
| cxr wrote:
| 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.
| danbruc wrote:
| The I will have to read the thesis once more. Sigh. I am
| pretty sure it talks about APIs, that is an interface
| consumable by software. What a browser does, formatting
| and rendering a response, is not what I would call
| consuming an API.
| lolinder wrote:
| 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
| whstl wrote:
| _" 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 wrote:
| 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 wrote:
| _> "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.
| danbruc wrote:
| 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?
| natural219 wrote:
| 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
| anotherhue wrote:
| > A REST client needs little to no prior knowledge about how to
| interact with an application or server beyond a generic
| understanding of hypermedia.
|
| 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.
| sgeisenh wrote:
| Client means browser in this context.
| ivan_gammel wrote:
| Only if hypermedia API is based on HTML/HTTP, which is not
| necessarily the case.
| a_cardboard_box wrote:
| The client is the web browser. Firefox can be built entirely
| without any knowledge of what hacker news is, and you can still
| browse hacker news on it.
| kbenson wrote:
| I think you're providing evidence for their point? HN isn't
| exactly useful without a person to browse it. "A generic
| understanding of hypermedia" is easy to say, but may be much
| more complex in reality to encode into a set of rules that a
| program knows to follow.
|
| 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.
| whstl wrote:
| Hacker News is very useful to Googlebot, and it gets
| crawled by it every day. It is also useful for people
| programming Selenium etc to automate using it to collect
| data.
|
| 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, if you want something that's not
| HTML+browser.
| ivan_gammel wrote:
| Hypermedia can be domain-specific, which already includes a lot
| of knowledge about data and operations. In case of HTML client
| needs to know the semantics of all HTML tags and understand how
| forms work. JSON-based RMM level 3 API can require knowledge of
| the schema of domain model and logical names of operations,
| leaving a lot of business logic to server, e.g. availability of
| certain operations in current security context. Client can
| render a button based on whether an operation with given name
| is mentioned in response or not instead of checking user roles
| etc.
| dsego wrote:
| You are supposed to define custom hypermedia types (instead of
| application/json which is generic, you have
| application/foobar+xml).
| whstl wrote:
| That's probably the most important post here. Whenever this
| discussion comes up, people believe that HATEOAS is about
| magic clients consuming arbitrary JSON APIs. It's not. In
| HATEOAS the URLs can be arbitrary, but the format cannot.
| spankalee wrote:
| Your comment is being misunderstood, maybe because of the way
| you phrased it, but you have a point: a generic client might be
| able to traverse links of arbitrary data, but it won't know
| what they mean or why to traverse the links.
|
| 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.
| [deleted]
___________________________________________________________________
(page generated 2023-08-01 23:02 UTC)