4 ms·

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 cl

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

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.

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