4 ms·

> "What you did not do is build an REST API" The API here is HTML + HTTP. That's it. A website is, as far as the API is concerned, just the content. > "I want

by whstl 3y ago

> "What you did not do is build an REST API" The API here is HTML + HTTP. That's it. A website is, as far as the API is concerned, just the content. > "I want to get the data and compute some statistics on it. For that I need to know the structure of the data in advance, need to know which URLs to retrieve, which operations to perform, which data structures to expect" Not needing to know the structure to automate usage of the content is not something that was exactly "promised" by REST. REST/HATEOAS is only about having standardized formats to display the hypermedia, make it discoverable within constraints (a browser for HTTP/HTML, a database program for OData, etc). Even with websites, I might need previous knowledge to know where to navigate to, which URLs to access. When I come to Hacker News, I always click on "threads" at the top to see if anyone replied me. This is often discovered thanks to hypermedia (in this case a link). But in my case someone had to point it out to me (this is analogous to documentation). > "So what am I still not getting?" My assumption, but since you asked: I think you're expecting the original REST paper and hypermedia to be something that it isn't, and to apply to things it isn't supposed to. You're trying to apply it to arbitrary APIs that are supposed to be consumed exclusively by custom software. This doesn't really match its model or intent. HTTP/HTML content is consumed by browsers. OData content is consumed by Excel, Access etc. AtomPub content is consumed by publishing/blogging/etc software. GData is a fun one: it is (was?) used as a foundation of traditional API clients. Another assumption, but perhaps you're expecting hypermedia to replace something else? You're mentioning "WSDL, OpenAPI and friends". Well, those are perfectly fine, and they're orthogonal to REST and hypermedia. GData is a good example: Google APIs used GData as a foundation, but actually needed extra documentation and extra code on top to drive users to the correct endpoints. The "discoverable" advantage of hypermedia APIs does not mean that applications should be intelligent and discover how to use the API just by accessing it. This is possible, don't get me wrong, but there will be massive constraints: either you build HTML/CSS/JS to allow arbitrary apps, or you have a simple tables app that consumes ODAta. If you want a fancy iPhone app, you'll have to start hardcoding a lot of assumptions into the app. The H of HATEOAS means hypermedia, a term created by Ted Nelson in the 60s. It's related to hypertext, which is the HT of HTML and HTTP. HATEOAS/REST is about creating hypermedia APIs, including HTML/HTTP. This means rich context, like Wikipedia, a database, or a Website. Not everything matches this. The app I work on doesn't. And that's completely fine.

danbruc 3y ago
Okay, I guess now the pieces are falling into place, the same conclusion just occurred to me in a different part of the thread, HTTP is the REST API and not an API build on top of HTTP. I will read some things again with that in mind, but currently my primary thought is how confusingly HATEOAS seems to be explained everywhere. If I see the bank account example where I can inspect account balances and make transfers, I of course assume we are talking about some banking API and it never occurred to me in all the years that we are actually talking about HTTP. After all, when I have to implement or consume an API, it will be the banking API, not HTTP. If I write or consume some SOAP service, there is an existing SOAP implementation on top of which I work but I rarely think of SOAP itself as an API, even though it of course is.
- whstl 3y ago
  Yes. The goal of the paper is to define clients that are 100% decoupled from the applications being served by some server. The browser is of course the best example of that. The only "shared knowledge" is in HTTP and in the format (HTML, OData, AtomPub). Excel consuming arbitrary OData is another example, Excel only knows HTTP and OData, and it's able to consume arbitrary data sources. If you want to have, say, a more user-friendly iPhone banking app, that's probably not gonna be an hypermedia app, it's just a regular application that's specific to your bank. This is not decoupled! Which is 100% fine, especially for user friendliness. For this you can start hardcoding URLs and baking in some assumptions, customizing some screens in the app. All of that is fine, but it's beyond the scope of "pure" hypermedia. Which is fine.
e12e 3y ago
Excellent points. As for: > My assumption, but since you asked: I think you're expecting the original REST paper and hypermedia to be something that it isn't, and to apply to things it isn't supposed to. You're trying to apply it to arbitrary APIs that are supposed to be consumed exclusively by custom software. I just want to point out that Fielding in his thesis details many different types of architectures. His focus is on REST and hypermedia - and especially how it fits well with efficient and correct caching. But he talks about movable code (java applets, or essentially also modern JavaScript applications like those built around React), RPC etc. I think the thesis remains relevant exactly because it's not only about REST.

by whstl 3y ago

danbruc 3y ago

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

whstl 3y ago
Yes. The goal of the paper is to define clients that are 100% decoupled from the applications being served by some server. The browser is of course the best example of that. The only "shared knowledge" is in HTTP and in the format (HTML, OData, AtomPub). Excel consuming arbitrary OData is another example, Excel only knows HTTP and OData, and it's able to consume arbitrary data sources. If you want to have, say, a more user-friendly iPhone banking app, that's probably not gonna be an hypermedia app, it's just a regular application that's specific to your bank. This is not decoupled! Which is 100% fine, especially for user friendliness. For this you can start hardcoding URLs and baking in some assumptions, customizing some screens in the app. All of that is fine, but it's beyond the scope of "pure" hypermedia. Which is fine.

e12e 3y ago

Excellent points. As for: > My assumption, but since you asked: I think you're expecting the original REST paper and hypermedia to be something that it isn't, and to apply to things it isn't supposed to. You're trying to apply it to arbitrary APIs that are supposed to be consumed exclusively by custom software. I just want to point out that Fielding in his thesis details many different types of architectures. His focus is on REST and hypermedia - and especially how it fits well with efficient and correct caching. But he talks about movable code (java applets, or essentially also modern JavaScript applications like those built around React), RPC etc. I think the thesis remains relevant exactly because it's not only about REST.