11 ms·

The client knows nothing about the API end points associated with this data, except via URLs and hypermedia controls (links and forms) discoverable within the H

by Joeri 4y ago

The client knows nothing about the API end points associated with this data, except via URLs and hypermedia controls (links and forms) discoverable within the HTML itself. If the state of the resource changes such that the allowable actions available on that resource change (for example, if the account goes into overdraft) then the HTML response would change to show the new set of actions available. If the client knows nothing about the meaning of the responses, it cannot do anything with them but show them to a human for interpretation. This would suggest a restful api is not made for system-to-system communication, but requires human mediation at every step of the way, which is precisely not how api’s are used. In short, this definition of restful api’s can’t be right, because it suggests restful interfaces aren’t api’s at all. Once a programmer adds code to parse the responses and extract meaningful data, treating the restful interface as an api, the tight coupling between client and server reappears.

simiones 4y ago
This is a wrong understanding of that point. The HATEOAS model is designed for one thing: clients and servers that are developed independently of each other. This matches how the Web is designed (browsers and servers are not developed together), but does not match how most Web Apps are developed (there is almost universally a single entity controlling both the server and the client(s) for that app). The point of HATEOAS-style REST APIs is that the client should decide what it can do based entirely on the responses it receives from the server and its understanding of the data model - not in any way on its own knowledge of what the server may be doing. This allows both to evolve separately, while still being able to communicate. To contrast the two approaches, let's say we are building a clone of HN. In the more common web app approach, our client may work like this: 1. Send a POST to https://auth.hnclone.com/login with {"username": "user", "password": "pass"}; wait for a 200 OK and a cookie 2. Send a GET request to https://hnclone.com/threads?id=user (including the cookie) and display the results to the user In the REST approach, our client and server could work like this: 1. Send a GET to https://hnclone.com; expect a body that contains {"links": [{"rel": "threads", "href": "https://hnclone.com/threads", "query_params": [{"name":"id", "role": "username"}]}]} 2. Send a GET request to the URL for rel="threads", populating the query param with role="username" with the stored username -> get a 401 NOT AUTHORIZED response with a body like {"links": [{"rel": "auth_page", "href": "https://auth.hnclone.com"}]} 3. Send a GET request to the URL for auth_page and expect a response that contains {"links": [{"rel": "login", "href": "https://auth.hnclone.com/login"}]} 4. Send a POST request to the link with rel == "login" with a body of {"username": "user", "password": "pass"}, expecting a 200 OK response and a cookie 5. Re-send the request to the URL for rel="threads" with the extra cookies, and now get the threads you want to show More complicated, but the client and server can now evolve more independently - they only have to agree on the meanings of the documents they exchange. The server could move its authentication to https://hnclone.com/api/auth https://hnclone.com/api/auth and the client from 2 years ago would still work. The server could add (optional) support for OAUTH without breaking old clients. You could even go further and define custom media formats and implement media format negotiation between client and server - the JSON format I described could be an explicit media format, and your API could evolve by adding new versions, relying on client Accept headers to decide which version to send. Now, is this extra complexity (and slowness!) worthwhile to your use case? This depends greatly. For a great many apps, it's probably not. For some, it probably is. It has definitely proven to be extremely useful for building web browsers that can automatically talk to any HTTP server out there without custom Google/Facebook/Reddit/etc. plugins to work properly.
- Jasper_ 4y ago
  How do you know that the specific login page is where you send the username/password? What if the sevrer changes the login flow to be a 2-part process? What if the clone wants to add an extra challenge like TOTP? The kinds of changes people are interested in are usually related to changing URLs, and those don't seem very valuable to me for the amount of complexity this flow adds. And ironically enough, the "URL changing" part we already have covered in the old system fine, with HTTP Redirect messages.
jaaron 4y ago
> "This would suggest a restful api is not made for system-to-system communication, but requires human mediation at every step of the way" Which is exactly what REST was originally designed to do: provide an architecture for the Internet (not your app or service) that allows for humans using software clients to interact with services developed by programmers other than those which developed the clients. It was about an interoperable, diverse Internet. If the distributed application is not developed across distributed organizations, particularly independent unassociated organizations, then the architectural style of REST is overkill for what you intend and you could have just kept using RPC the whole time. The point of the later RESTful API movement was to create distributed applications that leveraged the underlying architecture principles of the internet within their smaller distributed application. The theory being that this made the application more friendly and native to the broader internet, which I do agree is true, but was never the original point of REST. That said, xcamvber [1] is right: this is me being an old person fighting an old person battle. [1] https://news.ycombinator.com/item?id=32143382 https://news.ycombinator.com/item?id=32143382
- mywittyname 4y ago
  People took the useful ideas and tossed the rest. The whole idea of embedding links into the data that describe available operations was not seen as useful, because most web pages already do that. That was not a problem that needed to be solved. But the concept of resource-oriented architectures which leveraged HTTP verbs to act on data with descriptive URIs was extremely useful in an era when interactions with web servers would look something like POST /common/backend/doActMgt.pl Books like RESTful Web Services came out in 2007 and focused almost entirely on resource-oriented architecture. There's not really much mention of hypermedia in it. It's mostly about building API endpoints. It also referenced AWS S3 (wow, S3 is old) a lot and treated it as a reference implementation / proof of concept that the idea works and is scalable.
  - forty 4y ago
    Did you mean: People took the useful ideas and tossed the REST ? ;)
Sohcahtoa82 4y ago
I wish I could upvote this 100 times. REST, in its most strict form, feels like it was designed for humans to directly interact with. But this is exceptionally rare. Access will nearly always be done programmatically, at which point a lot of the cruft of REST is unnecessary.
- masklinn 4y ago
  > REST, in its most strict form, feels like it was designed for humans to directly interact with. It was literally extracted from the browser’s interaction model so… kinda?
  - ninkendo 4y ago
    But browsers already have HTML for this. Links are just <a> tags. POST endpoints are exposed with <form>, etc. Webpages. Why do we need a separate concept for this thing called REST if it just reduces to hypermedia in the end?
    - jgwil2 4y ago
      It seems like the article is basically calling REST an architecture or set of conventions that well-designed websites should adhere to, leaving APIs in the literal sense of the term basically out of it entirely. I mean, you could write code to parse any structured data, but if it can change anytime (because it's self-documenting?) then I'm not sure why you would bother.
      - jackling 4y ago
        I don't think that's what the article was saying. It was mainly pointing out the way people incorrectly use the term REST. I don't think the author was saying that well-designed websites should adhere to it, but rather sites that say they're REST but have APIs that are not RESTful. An HTML response is able to be parsed and interpreted by the browser, and doesn't need any special client code to interpret its meaning. It understands what's a link, and the actions it can perform on it just using the response itself. I'd argue that it's still an API, since it's still parsed, interfaced with by the system. The major difference is that the interface is uniform.
zozbot234 4y ago
> If the client knows nothing about the meaning of the responses, it cannot do anything with them but show them to a human for interpretation. The client "knows nothing about the meaning of the responses" only inasmuch as it intentionally abstracts away from that meaning to the extent practicable for the intended application. Of course, the requirements of a human looking at some data are not the same as those of a machine using that same data in some automated workflow. Linked Data standards (usable even within JSON via JSON-LD) have been developed to enable a "hyperlink"-focused approach to these concerns, so there's plenty of overlap with REST principles.
recursivedoubts 4y ago
I am the author and I agree with most of what you are saying here, REST and HATEOAS are for humans: https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h... I disagree that it isn't an API, but that's a definition quibble. It is probably more profitable to talk about RESTful systems rather than RESTful APIs, since people think API == machines talking.
- SilasX 4y ago
  That feels like a pretty significant quibble. API stands for “application programming interface”. If you cannot write an application to programmatically interface with it, why would you call it an API? What you and the parent see REST as, should be called an HPAI: “human-poking-around interface”.
  - recursivedoubts 4y ago
    REST is an application programming interface for RESTful systems, interpreted by RESTful clients (browsers). Generic Data APIs, and the clients that use them, are different and have different needs.
    - SilasX 4y ago
      >REST is an application programming interface for RESTful systems, interpreted by RESTful clients (browsers). No, the interpretation is done by the human using the browser, which is what makes it not programmable against, violating the P in the acronym.
      - recursivedoubts 4y ago
        The brower, a hypermedia client, sees the links, for example, in the API responses and renders them for the human to interact with. The browser is a hypermedia client, working against a hypermedia API. It not understanding the content of the responses beyond the hypermedia layer is by design: that's the uniform interface of REST. I mean, this is quibbling over definitions. I agree entirely with your general point that REST hasn't worked out well as a network architecture for non-hypermedia clients.
k__ 4y ago
This. I read quite much about REST and HATEOAS, and it didn't made any sense to me. Somehow the "magic sauce" was missing. How should a client that doesn't know anything about an API interpret it's meaning? I felt like an idiot. Like there was some high end algorithm or architecture that completely eluded me. But it the end, it probably just meant, HATEOAS is for humans.
- falcolas 4y ago
  I feel almost like there’s an implicit dependency on GAI for interpreting HATEOS properly.
  - k__ 4y ago
    Yes. I thought so too! I just had the impression, that this was too much and I'm simply missing something obvious.
mattarm 4y ago
By my read of this "REST API" is a near oxymoron. It was never supposed to be an "API" in the sense that a program consumes it. It was originally described as "Representational State Transfer (REST) architectural style for distributed hypermedia systems" with a focus on describing resources in generic ways for consumption by hypermedia systems (not arbitrary programs!). I think this is most clearly described by two things Fielding wrote (and the original article links to): https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc... https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...
- cpill 4y ago
  > describing resources in generic ways the trouble is that HTML is anything but generic. If you've ever tried to write a web scraper that can be used on _any_ webapage you quickly discover that its near impossible. I use to belived that there should be one way to use HTML to describe the page content and the rest should be CSS but gave up as its completely inflexable and the approch has been abandoned for simply describing presentation as this is actually practical. You'd need a HTML structural standard, but that will get mostly ignore (as have most of the W3Cs recommendations on that subject). As you said "REST" and "RESTful API" are different beast, i guess the "-ful" should be more of an "-ish".
  - ReactiveJelly 4y ago
    Well pound for pound most websites want to sell ads to human eyes and categorically block any robot that doesn't have a human piloting it. Your best bet at finding standardized public data is projects that _want_ to be read and stored and don't make money, like Wikipedia
  - jonhohle 4y ago
    That was the idea behind micro formats and semantic HTML. The only people who ever used it thought the same as you, but there were never enough for any critical mass.
  - 4y ago
jrochkind1 4y ago
I would say "semantic web" is the key technology in an attempt to make that kind of API that doesn't need human intervention. My understanding of the vision is that when all your responses all described using (fielding original) REST API's via RDF, using URI identifiers everywhere -- then a client that has never seen a particular server can still automatically figure out useful things to do with it (per the end-user's commands, expressed to the software in configuration or execution by some UI), solely by understanding enough of the identifiers in use. You wouldn't need to write new software for each new API or server, even novel servers doing novel things would re-use a lot of the same identifiers, just mixing and matching them in different ways, and the client could still "automatically" make use of them. I... don't think it's worked out very well. As far as actually getting to that envisioned scenario. I don't think "semantic web" technology is likely to. I am not a fan. But I think "semantic web" and RDF is where you get when you try to take HATEOS/REST and deal with what you're describing: What do we need to standardize/formalize so the client can know something about the meaning of the response and be able to do something with it other than show it to a human, even for a novel interface? RDF, ostensibly. The fielding/HATEOS REST, and the origial vision of RDF/semantic web... are deeply aligned technologies, part of the same ideology or vision.
- jdougan 4y ago
  It doesn't need the full SemWeb treatment to work. All it needs is a reasonable descriptive language such as SIREN [1] along with Web Link Relations list the IETF maintains already. 1. https://github.com/kevinswiber/siren https://github.com/kevinswiber/siren
- checker 4y ago
  You have a typo, it's HATEOAS (Hypermedia as the Engine of Application State).
vgel 4y ago
This is incorrect. There are plenty of machines that read the web: web scrapers, and they've fostered a diverse ecosystem of tools. Search engines, archival tools, ML dataset collection, browser extensions and more are able to work with hypertext because it's self-describing. A new site can pop up and Google can index it without knowing if it's a blog, forum, storefront, or some new genre of website that may be invented in 30 years.
- dgudkov 4y ago
  >Search engines, archival tools, ML dataset collection, browser extensions and more are able to work with hypertext because it's self-describing They only read state but never modify it. So it misses the whole point of interaction with a web resource.
  - vgel 4y ago
    They can: my password manager auto-logs-in for me. Various tools will automatically find and click the "unsubscribe" link on a mailing list website. Scalper bots buy and resell all kinds of products by navigating web stores (unfortunately). etc. Yes, generally it's more dangerous to make destructive actions automatically on a site you don't know the structure of than against an API a human has considered and designed against. But think about it: the design of HTTP / REST makes that possible. If you tried to write a bot that downloaded random Windows apps and clicked random buttons to "scrape" them, you could easily click a "delete all my files" button in a file management app (not even considering malware). In a REST API, that's not really possible by just issuing GET requests. Google can safely GET any random URL on your site with no harm, unless you've made a serious programming error.
    - Sohcahtoa82 4y ago
      > my password manager auto-logs-in for me. Various tools will automatically find and click the "unsubscribe" link on a mailing list website. Those tools work by making assumptions. For example, your password manager looks for text input fields with the name attribute set to "user", "username", "login", "email", "account", etc. Create a page with a login form, but name the user field some gibberish, and I bet your password manager won't be able to auto-login. > Scalper bots buy and resell all kinds of products by navigating web stores (unfortunately). etc. And each of those bots will need to be written for each store. ie, a bot written to scalp products from Amazon won't work on BestBuy.com.
wwweston 4y ago
> If the client knows nothing about the meaning of the responses, it cannot do anything with them but show them to a human for interpretation. This is the best counterpoint in this discussion and it deserves a lot of reflection. But that reflection should include the realization that this is what the browser does all the time. Browsers don't have any particular semantic model in their head of what any particular form action or hyperlink "means" in terms of domain logic... but they do have some semantics for broad classes of verbs and other interactions associated with markup-represented potential actions, and so they serve as an agent presenting these to the user who does whatever wetware does in processing domain semantics and logic and makes a choice. This has worked so well over the last 30 years it's been the biggest platform ever. We're now in territory where we're creating software that's almost alarmingly good at doing some semantic processing out of no particular structure. The idea that we're facing a dead end in terms of potential for clients to automatically get anything out of a hypertext API seems pretty tenuous to me.
- marcosdumay 4y ago
  The original requirement is something on the direction of generalizing HTTP into a protocol for transferring all kinds of data with a human representation interlinked. What would be very interesting, if HTML didn't evolve with the goal of containing all kinds of data with a human representation too. But now it's mostly redundant and people just prefer encoding things in HTML.
NonNefarious 4y ago
EXACTLY. Regurgitators of the HATEOAS mantra never address this. Instead you get statements like one in this article: "the HTML response "carries along" all the API information necessary to continue interacting with the system directly within itself." No, it doesn't. It's a list of URLs, which doesn't even indicate what operations they accept. The only thing REST supports, according to this philosophy, is a user manually traipsing through the "API" by clicking on stuff. Thanks for summing it up so succinctly; I thought maybe I was missing something.
- recursivedoubts 4y ago
  I'm the author, and I agree with you: a list of URLs jammed in a JSON response isn't much of a useful hypermedia affordance and, even if it was, what would some code do with it besides passing it on to a human to deal with? Old web 1.0 applications, however, let you do a lot more than traipse through an API by clicking on stuff: you can send emails, update documents and on an on, all through links and forms. The HTML, in this system, does "carry along" all the API information necessary for the client (the browser) to interact with the resources it is representing. It relies on the human user to select exactly which actions to take, which is why I say "HATEOAS is for Humans", and wrote an article on exactly that.
  - NonNefarious 4y ago
    Actually, in those cases the client is a person; the browser is only the transport mechanism. But indeed we agree on the "for humans" problem. I'm inclined to accept widely-repeated guidelines on technology that I'm just learning, but this is another instance where the fallacy became obvious when it was time to implement something. Kinda like any attempt to use a lot of inheritance in OOP, which is now recognized as silly. I assume that a lot of problems are "solved," but continue to be surprised that they aren't. I defined an API using OpenAPI and am now trying to generate code for it and do some prototyping, but the whole ecosystem is a mess and the standard itself is only now shaking off some truly dumb gaffes.
    - recursivedoubts 4y ago
sanderjd 4y ago
This is my criticism of the architecture.as well. But to try to take it seriously for a moment: I think the idea is supposed to be that a client can be programmed to understand the data types, but not the layout. So a programmer can teach a client that if it gets a content type of `application/json+balances`, and it sees, like `'links': [ 'type': 'withdraw', 'method': 'post', 'url': ..., 'params': { 'amount': 'int' } ]`, then it can know to send that method to that URL with that param and that it semantically means a withdrawal. That's all encoded into the documentation of the data type, rather than the API. I personally consider this all overly clever and not very useful, but I think that's the idea.
kragen 4y ago
Fielding isn't saying the client should know nothing about the meaning of the responses. He's saying that what the client knows about the meaning of the responses is derived by interpreting them according to the media type, which doesn't have to be HTML, rather than, for example, by looking at the URL. Quoting from what Fielding wrote in his post and comments: > A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). ... > When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions. Hypermedia is just an expansion on what text means to include temporal anchors within a media stream; most researchers have dropped the distinction. > Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types. That is, htmx.org or intercoolerjs.org might argue that "HATEOAS is [exclusively] for humans", but Roy Fielding doesn't agree, or didn't in 02008. — ⁂ — While I'm arguing, I'd also like to take exception to the claim that this discussion is irrelevant to anything people are doing today. It's an "old person battle," as some say, in the sense that old people are the people who have enough perspective to know what matters and what doesn't. REST matters, because it is an architectural style that enables the construction of applications that can endure for decades, permitting the construction of applications that evolve without a central administrator, remaining backwards-compatible with decades-old software, and can include billions of simultaneous users. This is an important problem to solve, the WWW isn't the last such application anyone ever needs to build, and JSON RPC interfaces can't build one. The trouble with redefining "REST" to mean "not REST" is that the first step in learning known techniques to solve a problem is learning the terminology that people use to explain the techniques. If you think you know the terminology, but you have the wrong definition in your mind, you will not be able to understand the explanations, and you will not be able to figure out why you can't understand them, until you finally figure out that the definition you learned was wrong.
- recursivedoubts 4y ago
  2008 Fielding definitely wouldn't agree with me that HATEOAS is for humans. That's a conclusion I came to after watching it never catch on in the JSON API space and then trying to come up with an explanation as to why. I'd love to hear what he thinks of the idea. Thank you for the thoughtful comment!
peeters 4y ago
This is right on the money in identifying the continual battle with using a hypermedia API for system-to-system communication. There comes a time where you realize that what you're building is great for discoverability, but not for instructing a computer to do something on your behalf. That said, the situation isn't entirely dire. With some standard linking conventions (e.g RFC 8288 [1]), you can largely make an API that is pleasant to interact with in code as well. That the links/actions are enumerated is good for humans to learn how to manipulate the resource. That they have persistent rels is good for telling a computer how to do the same. Think <link rel="stylesheet" href="foo"> as an example. A human reading the HTML source will see that there's a related stylesheet available at "foo". But a program wanting to render HTML will check for the existence of links with rel="stylesheet". 1: https://datatracker.ietf.org/doc/html/rfc8288#section-2.1.2 https://datatracker.ietf.org/doc/html/rfc8288#section-2.1.2
irrational 4y ago
Why is the front end coder parsing anything? Just display the HTML.
Aeolun 4y ago
I don’t understand how anyone would ever expect a REST API to work to send information into a system? So far everything I’ve seen in the article is for reading. You’d still need some generalized format for the client to get some form of input schema, and if you send the input schema for every action every time you retrieve a resource, things quickly become very data intensive.
- NoGravitas 4y ago
  Have you ever filled out an HTML form that was handled server-side? Is you, you've sent data into a REST system.
afiori 4y ago
It is not "If the client knows nothing about the meaning of the responses" but "The client knows nothing about the API end points associated with this data" This means that if "/api/item/search?filter=xxxxx" returns an array of ids then you don't have to guess that item prices can be fetched by "/api/item/price?id=nnn" but this url (maybe in template form) needs to be provided by either the "/api/item/search?filter=xxxxx" query or another call you have previously executed. So very similarly to how you click on links on a website. You often have a priori knowledge of the semantic of the website, but you visit the settings page by clicking of the settings link, not by manually going to "website.example/settings". PS: these links could be provided by a separate endpoint, but this structure is often useful for things like pagination: instead of manually incrementing offsets each paginated reply can include links for next/previous pages and other relevant links. These need not be full URLs also relative URLs, just URL query fragments, or a JSON description of the query would work (together with a template URL from somewhere else)

by Joeri 4y ago

simiones 4y ago

This is a wrong understanding of that point. The HATEOAS model is designed for one thing: clients and servers that are developed independently of each other. This matches how the Web is designed (browsers and servers are not developed together), but does not match how most Web Apps are developed (there is almost universally a single entity controlling both the server and the client(s) for that app). The point of HATEOAS-style REST APIs is that the client should decide what it can do based entirely on the responses it receives from the server and its understanding of the data model - not in any way on its own knowledge of what the server may be doing. This allows both to evolve separately, while still being able to communicate. To contrast the two approaches, let's say we are building a clone of HN. In the more common web app approach, our client may work like this: 1. Send a POST to https://auth.hnclone.com/login with {"username": "user", "password": "pass"}; wait for a 200 OK and a cookie 2. Send a GET request to https://hnclone.com/threads?id=user (including the cookie) and display the results to the user In the REST approach, our client and server could work like this: 1. Send a GET to https://hnclone.com; expect a body that contains {"links": [{"rel": "threads", "href": "https://hnclone.com/threads", "query_params": [{"name":"id", "role": "username"}]}]} 2. Send a GET request to the URL for rel="threads", populating the query param with role="username" with the stored username -> get a 401 NOT AUTHORIZED response with a body like {"links": [{"rel": "auth_page", "href": "https://auth.hnclone.com"}]} 3. Send a GET request to the URL for auth_page and expect a response that contains {"links": [{"rel": "login", "href": "https://auth.hnclone.com/login"}]} 4. Send a POST request to the link with rel == "login" with a body of {"username": "user", "password": "pass"}, expecting a 200 OK response and a cookie 5. Re-send the request to the URL for rel="threads" with the extra cookies, and now get the threads you want to show More complicated, but the client and server can now evolve more independently - they only have to agree on the meanings of the documents they exchange. The server could move its authentication to https://hnclone.com/api/auth https://hnclone.com/api/auth and the client from 2 years ago would still work. The server could add (optional) support for OAUTH without breaking old clients. You could even go further and define custom media formats and implement media format negotiation between client and server - the JSON format I described could be an explicit media format, and your API could evolve by adding new versions, relying on client Accept headers to decide which version to send. Now, is this extra complexity (and slowness!) worthwhile to your use case? This depends greatly. For a great many apps, it's probably not. For some, it probably is. It has definitely proven to be extremely useful for building web browsers that can automatically talk to any HTTP server out there without custom Google/Facebook/Reddit/etc. plugins to work properly.

Jasper_ 4y ago
How do you know that the specific login page is where you send the username/password? What if the sevrer changes the login flow to be a 2-part process? What if the clone wants to add an extra challenge like TOTP? The kinds of changes people are interested in are usually related to changing URLs, and those don't seem very valuable to me for the amount of complexity this flow adds. And ironically enough, the "URL changing" part we already have covered in the old system fine, with HTTP Redirect messages.

jaaron 4y ago

> "This would suggest a restful api is not made for system-to-system communication, but requires human mediation at every step of the way" Which is exactly what REST was originally designed to do: provide an architecture for the Internet (not your app or service) that allows for humans using software clients to interact with services developed by programmers other than those which developed the clients. It was about an interoperable, diverse Internet. If the distributed application is not developed across distributed organizations, particularly independent unassociated organizations, then the architectural style of REST is overkill for what you intend and you could have just kept using RPC the whole time. The point of the later RESTful API movement was to create distributed applications that leveraged the underlying architecture principles of the internet within their smaller distributed application. The theory being that this made the application more friendly and native to the broader internet, which I do agree is true, but was never the original point of REST. That said, xcamvber [1] is right: this is me being an old person fighting an old person battle. [1] https://news.ycombinator.com/item?id=32143382 https://news.ycombinator.com/item?id=32143382

mywittyname 4y ago
People took the useful ideas and tossed the rest. The whole idea of embedding links into the data that describe available operations was not seen as useful, because most web pages already do that. That was not a problem that needed to be solved. But the concept of resource-oriented architectures which leveraged HTTP verbs to act on data with descriptive URIs was extremely useful in an era when interactions with web servers would look something like POST /common/backend/doActMgt.pl Books like RESTful Web Services came out in 2007 and focused almost entirely on resource-oriented architecture. There's not really much mention of hypermedia in it. It's mostly about building API endpoints. It also referenced AWS S3 (wow, S3 is old) a lot and treated it as a reference implementation / proof of concept that the idea works and is scalable.
- forty 4y ago
  Did you mean: People took the useful ideas and tossed the REST ? ;)

Sohcahtoa82 4y ago

I wish I could upvote this 100 times. REST, in its most strict form, feels like it was designed for humans to directly interact with. But this is exceptionally rare. Access will nearly always be done programmatically, at which point a lot of the cruft of REST is unnecessary.

masklinn 4y ago
> REST, in its most strict form, feels like it was designed for humans to directly interact with. It was literally extracted from the browser’s interaction model so… kinda?
- ninkendo 4y ago
  But browsers already have HTML for this. Links are just <a> tags. POST endpoints are exposed with <form>, etc. Webpages. Why do we need a separate concept for this thing called REST if it just reduces to hypermedia in the end?
  - jgwil2 4y ago
    It seems like the article is basically calling REST an architecture or set of conventions that well-designed websites should adhere to, leaving APIs in the literal sense of the term basically out of it entirely. I mean, you could write code to parse any structured data, but if it can change anytime (because it's self-documenting?) then I'm not sure why you would bother.
    - jackling 4y ago
      I don't think that's what the article was saying. It was mainly pointing out the way people incorrectly use the term REST. I don't think the author was saying that well-designed websites should adhere to it, but rather sites that say they're REST but have APIs that are not RESTful. An HTML response is able to be parsed and interpreted by the browser, and doesn't need any special client code to interpret its meaning. It understands what's a link, and the actions it can perform on it just using the response itself. I'd argue that it's still an API, since it's still parsed, interfaced with by the system. The major difference is that the interface is uniform.

zozbot234 4y ago

> If the client knows nothing about the meaning of the responses, it cannot do anything with them but show them to a human for interpretation. The client "knows nothing about the meaning of the responses" only inasmuch as it intentionally abstracts away from that meaning to the extent practicable for the intended application. Of course, the requirements of a human looking at some data are not the same as those of a machine using that same data in some automated workflow. Linked Data standards (usable even within JSON via JSON-LD) have been developed to enable a "hyperlink"-focused approach to these concerns, so there's plenty of overlap with REST principles.

recursivedoubts 4y ago

I am the author and I agree with most of what you are saying here, REST and HATEOAS are for humans: https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h... I disagree that it isn't an API, but that's a definition quibble. It is probably more profitable to talk about RESTful systems rather than RESTful APIs, since people think API == machines talking.

SilasX 4y ago
That feels like a pretty significant quibble. API stands for “application programming interface”. If you cannot write an application to programmatically interface with it, why would you call it an API? What you and the parent see REST as, should be called an HPAI: “human-poking-around interface”.
- recursivedoubts 4y ago
  REST is an application programming interface for RESTful systems, interpreted by RESTful clients (browsers). Generic Data APIs, and the clients that use them, are different and have different needs.
  - SilasX 4y ago
    >REST is an application programming interface for RESTful systems, interpreted by RESTful clients (browsers). No, the interpretation is done by the human using the browser, which is what makes it not programmable against, violating the P in the acronym.
    - recursivedoubts 4y ago
      The brower, a hypermedia client, sees the links, for example, in the API responses and renders them for the human to interact with. The browser is a hypermedia client, working against a hypermedia API. It not understanding the content of the responses beyond the hypermedia layer is by design: that's the uniform interface of REST. I mean, this is quibbling over definitions. I agree entirely with your general point that REST hasn't worked out well as a network architecture for non-hypermedia clients.

k__ 4y ago

This. I read quite much about REST and HATEOAS, and it didn't made any sense to me. Somehow the "magic sauce" was missing. How should a client that doesn't know anything about an API interpret it's meaning? I felt like an idiot. Like there was some high end algorithm or architecture that completely eluded me. But it the end, it probably just meant, HATEOAS is for humans.

falcolas 4y ago
I feel almost like there’s an implicit dependency on GAI for interpreting HATEOS properly.
- k__ 4y ago
  Yes. I thought so too! I just had the impression, that this was too much and I'm simply missing something obvious.

mattarm 4y ago

By my read of this "REST API" is a near oxymoron. It was never supposed to be an "API" in the sense that a program consumes it. It was originally described as "Representational State Transfer (REST) architectural style for distributed hypermedia systems" with a focus on describing resources in generic ways for consumption by hypermedia systems (not arbitrary programs!). I think this is most clearly described by two things Fielding wrote (and the original article links to): https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc... https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...

cpill 4y ago
> describing resources in generic ways the trouble is that HTML is anything but generic. If you've ever tried to write a web scraper that can be used on _any_ webapage you quickly discover that its near impossible. I use to belived that there should be one way to use HTML to describe the page content and the rest should be CSS but gave up as its completely inflexable and the approch has been abandoned for simply describing presentation as this is actually practical. You'd need a HTML structural standard, but that will get mostly ignore (as have most of the W3Cs recommendations on that subject). As you said "REST" and "RESTful API" are different beast, i guess the "-ful" should be more of an "-ish".
- ReactiveJelly 4y ago
  Well pound for pound most websites want to sell ads to human eyes and categorically block any robot that doesn't have a human piloting it. Your best bet at finding standardized public data is projects that _want_ to be read and stored and don't make money, like Wikipedia
- jonhohle 4y ago
  That was the idea behind micro formats and semantic HTML. The only people who ever used it thought the same as you, but there were never enough for any critical mass.
- 4y ago

jrochkind1 4y ago

I would say "semantic web" is the key technology in an attempt to make that kind of API that doesn't need human intervention. My understanding of the vision is that when all your responses all described using (fielding original) REST API's via RDF, using URI identifiers everywhere -- then a client that has never seen a particular server can still automatically figure out useful things to do with it (per the end-user's commands, expressed to the software in configuration or execution by some UI), solely by understanding enough of the identifiers in use. You wouldn't need to write new software for each new API or server, even novel servers doing novel things would re-use a lot of the same identifiers, just mixing and matching them in different ways, and the client could still "automatically" make use of them. I... don't think it's worked out very well. As far as actually getting to that envisioned scenario. I don't think "semantic web" technology is likely to. I am not a fan. But I think "semantic web" and RDF is where you get when you try to take HATEOS/REST and deal with what you're describing: What do we need to standardize/formalize so the client can know something about the meaning of the response and be able to do something with it other than show it to a human, even for a novel interface? RDF, ostensibly. The fielding/HATEOS REST, and the origial vision of RDF/semantic web... are deeply aligned technologies, part of the same ideology or vision.

jdougan 4y ago
It doesn't need the full SemWeb treatment to work. All it needs is a reasonable descriptive language such as SIREN [1] along with Web Link Relations list the IETF maintains already. 1. https://github.com/kevinswiber/siren https://github.com/kevinswiber/siren
checker 4y ago
You have a typo, it's HATEOAS (Hypermedia as the Engine of Application State).

vgel 4y ago

This is incorrect. There are plenty of machines that read the web: web scrapers, and they've fostered a diverse ecosystem of tools. Search engines, archival tools, ML dataset collection, browser extensions and more are able to work with hypertext because it's self-describing. A new site can pop up and Google can index it without knowing if it's a blog, forum, storefront, or some new genre of website that may be invented in 30 years.

dgudkov 4y ago
>Search engines, archival tools, ML dataset collection, browser extensions and more are able to work with hypertext because it's self-describing They only read state but never modify it. So it misses the whole point of interaction with a web resource.
- vgel 4y ago
  They can: my password manager auto-logs-in for me. Various tools will automatically find and click the "unsubscribe" link on a mailing list website. Scalper bots buy and resell all kinds of products by navigating web stores (unfortunately). etc. Yes, generally it's more dangerous to make destructive actions automatically on a site you don't know the structure of than against an API a human has considered and designed against. But think about it: the design of HTTP / REST makes that possible. If you tried to write a bot that downloaded random Windows apps and clicked random buttons to "scrape" them, you could easily click a "delete all my files" button in a file management app (not even considering malware). In a REST API, that's not really possible by just issuing GET requests. Google can safely GET any random URL on your site with no harm, unless you've made a serious programming error.
  - Sohcahtoa82 4y ago
    > my password manager auto-logs-in for me. Various tools will automatically find and click the "unsubscribe" link on a mailing list website. Those tools work by making assumptions. For example, your password manager looks for text input fields with the name attribute set to "user", "username", "login", "email", "account", etc. Create a page with a login form, but name the user field some gibberish, and I bet your password manager won't be able to auto-login. > Scalper bots buy and resell all kinds of products by navigating web stores (unfortunately). etc. And each of those bots will need to be written for each store. ie, a bot written to scalp products from Amazon won't work on BestBuy.com.

wwweston 4y ago

> If the client knows nothing about the meaning of the responses, it cannot do anything with them but show them to a human for interpretation. This is the best counterpoint in this discussion and it deserves a lot of reflection. But that reflection should include the realization that this is what the browser does all the time. Browsers don't have any particular semantic model in their head of what any particular form action or hyperlink "means" in terms of domain logic... but they do have some semantics for broad classes of verbs and other interactions associated with markup-represented potential actions, and so they serve as an agent presenting these to the user who does whatever wetware does in processing domain semantics and logic and makes a choice. This has worked so well over the last 30 years it's been the biggest platform ever. We're now in territory where we're creating software that's almost alarmingly good at doing some semantic processing out of no particular structure. The idea that we're facing a dead end in terms of potential for clients to automatically get anything out of a hypertext API seems pretty tenuous to me.

marcosdumay 4y ago
The original requirement is something on the direction of generalizing HTTP into a protocol for transferring all kinds of data with a human representation interlinked. What would be very interesting, if HTML didn't evolve with the goal of containing all kinds of data with a human representation too. But now it's mostly redundant and people just prefer encoding things in HTML.

NonNefarious 4y ago

EXACTLY. Regurgitators of the HATEOAS mantra never address this. Instead you get statements like one in this article: "the HTML response "carries along" all the API information necessary to continue interacting with the system directly within itself." No, it doesn't. It's a list of URLs, which doesn't even indicate what operations they accept. The only thing REST supports, according to this philosophy, is a user manually traipsing through the "API" by clicking on stuff. Thanks for summing it up so succinctly; I thought maybe I was missing something.

recursivedoubts 4y ago
I'm the author, and I agree with you: a list of URLs jammed in a JSON response isn't much of a useful hypermedia affordance and, even if it was, what would some code do with it besides passing it on to a human to deal with? Old web 1.0 applications, however, let you do a lot more than traipse through an API by clicking on stuff: you can send emails, update documents and on an on, all through links and forms. The HTML, in this system, does "carry along" all the API information necessary for the client (the browser) to interact with the resources it is representing. It relies on the human user to select exactly which actions to take, which is why I say "HATEOAS is for Humans", and wrote an article on exactly that.
- NonNefarious 4y ago
  Actually, in those cases the client is a person; the browser is only the transport mechanism. But indeed we agree on the "for humans" problem. I'm inclined to accept widely-repeated guidelines on technology that I'm just learning, but this is another instance where the fallacy became obvious when it was time to implement something. Kinda like any attempt to use a lot of inheritance in OOP, which is now recognized as silly. I assume that a lot of problems are "solved," but continue to be surprised that they aren't. I defined an API using OpenAPI and am now trying to generate code for it and do some prototyping, but the whole ecosystem is a mess and the standard itself is only now shaking off some truly dumb gaffes.
  - recursivedoubts 4y ago

sanderjd 4y ago

This is my criticism of the architecture.as well. But to try to take it seriously for a moment: I think the idea is supposed to be that a client can be programmed to understand the data types, but not the layout. So a programmer can teach a client that if it gets a content type of `application/json+balances`, and it sees, like `'links': [ 'type': 'withdraw', 'method': 'post', 'url': ..., 'params': { 'amount': 'int' } ]`, then it can know to send that method to that URL with that param and that it semantically means a withdrawal. That's all encoded into the documentation of the data type, rather than the API. I personally consider this all overly clever and not very useful, but I think that's the idea.

kragen 4y ago

Fielding isn't saying the client should know nothing about the meaning of the responses. He's saying that what the client knows about the meaning of the responses is derived by interpreting them according to the media type, which doesn't have to be HTML, rather than, for example, by looking at the URL. Quoting from what Fielding wrote in his post and comments: > A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). ... > When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions. Hypermedia is just an expansion on what text means to include temporal anchors within a media stream; most researchers have dropped the distinction. > Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types. That is, htmx.org or intercoolerjs.org might argue that "HATEOAS is [exclusively] for humans", but Roy Fielding doesn't agree, or didn't in 02008. — ⁂ — While I'm arguing, I'd also like to take exception to the claim that this discussion is irrelevant to anything people are doing today. It's an "old person battle," as some say, in the sense that old people are the people who have enough perspective to know what matters and what doesn't. REST matters, because it is an architectural style that enables the construction of applications that can endure for decades, permitting the construction of applications that evolve without a central administrator, remaining backwards-compatible with decades-old software, and can include billions of simultaneous users. This is an important problem to solve, the WWW isn't the last such application anyone ever needs to build, and JSON RPC interfaces can't build one. The trouble with redefining "REST" to mean "not REST" is that the first step in learning known techniques to solve a problem is learning the terminology that people use to explain the techniques. If you think you know the terminology, but you have the wrong definition in your mind, you will not be able to understand the explanations, and you will not be able to figure out why you can't understand them, until you finally figure out that the definition you learned was wrong.

recursivedoubts 4y ago
2008 Fielding definitely wouldn't agree with me that HATEOAS is for humans. That's a conclusion I came to after watching it never catch on in the JSON API space and then trying to come up with an explanation as to why. I'd love to hear what he thinks of the idea. Thank you for the thoughtful comment!

peeters 4y ago

This is right on the money in identifying the continual battle with using a hypermedia API for system-to-system communication. There comes a time where you realize that what you're building is great for discoverability, but not for instructing a computer to do something on your behalf. That said, the situation isn't entirely dire. With some standard linking conventions (e.g RFC 8288 [1]), you can largely make an API that is pleasant to interact with in code as well. That the links/actions are enumerated is good for humans to learn how to manipulate the resource. That they have persistent rels is good for telling a computer how to do the same. Think <link rel="stylesheet" href="foo"> as an example. A human reading the HTML source will see that there's a related stylesheet available at "foo". But a program wanting to render HTML will check for the existence of links with rel="stylesheet". 1: https://datatracker.ietf.org/doc/html/rfc8288#section-2.1.2 https://datatracker.ietf.org/doc/html/rfc8288#section-2.1.2

irrational 4y ago

Why is the front end coder parsing anything? Just display the HTML.

Aeolun 4y ago

I don’t understand how anyone would ever expect a REST API to work to send information into a system? So far everything I’ve seen in the article is for reading. You’d still need some generalized format for the client to get some form of input schema, and if you send the input schema for every action every time you retrieve a resource, things quickly become very data intensive.

NoGravitas 4y ago
Have you ever filled out an HTML form that was handled server-side? Is you, you've sent data into a REST system.

afiori 4y ago

It is not "If the client knows nothing about the meaning of the responses" but "The client knows nothing about the API end points associated with this data" This means that if "/api/item/search?filter=xxxxx" returns an array of ids then you don't have to guess that item prices can be fetched by "/api/item/price?id=nnn" but this url (maybe in template form) needs to be provided by either the "/api/item/search?filter=xxxxx" query or another call you have previously executed. So very similarly to how you click on links on a website. You often have a priori knowledge of the semantic of the website, but you visit the settings page by clicking of the settings link, not by manually going to "website.example/settings". PS: these links could be provided by a separate endpoint, but this structure is often useful for things like pagination: instead of manually incrementing offsets each paginated reply can include links for next/previous pages and other relevant links. These need not be full URLs also relative URLs, just URL query fragments, or a JSON description of the query would work (together with a template URL from somewhere else)