4 ms·

> but no sane client will go around and request random server-provided urls to discover what is available Compare and contrast: what SQL admin GUI clients do t

by derefr 4y ago

> but no sane client will go around and request random server-provided urls to discover what is available Compare and contrast: what SQL admin GUI clients do to discover the DBMS schema. They essentially spider it. > Under HATEOAS the client would need to associate the knowledge of resource structure with a particular resource received. A promising identifier for this association would be the resource collection path, i.e. the URL. If the client needs to know the URLs, why have them in the response? The client does not need to know the URL; the client needs to know how to get to the URL. Have you ever written a web scraper, for a site that doesn't really enjoy being scraped, and so uses stuff like CSRF protection "synchronizer tokens"? To do/get anything on such a site, you can't just directly go to the thing; you have to start where a real browser would start, and click links / submit forms like a browser would do, to get there. HATEOAS is the idea that APIs should also work that way: "clicking links" and "submitting forms" from some well-known root resource to get to the API you know about. As with a scraper, it's the "link text" or the "form field names" — the delivered API — that you're assuming to be stable; not the URL structure. > Other problems include creating new resource - how the client is supposed to know the structure of to-be created resource, if there is none yet? The client has nothing to request to discover the resource structure and associations. What do you think HTML forms are, if not descriptions of resource templates? When you GET /foos, why do you think the browser result is a form? It's a description of how to make a foo (and, through the submit attribute, a place to send it to get it made.) Alternately, compare/contrast what Kubernetes does — exposes its resource schemas as documents, living in the same resource-hierarchy as the documents themselves live. > Also hypertext does not map well to JSON. In JSON you can not differenciate between data and metadata (i.e. links to other resources) It's right in the name: in HATEOAS, hypertext is the engine of application state. Hypertext as in, say, HTML. JSON is not hypertext, because it's not text — it's not a markup language like SGML/XML/HTML are. You realize that HTML is machine-readable, right? That you can respond to an XHR with HTML, and then parse it using the browser (or API client's) HTML parsing capabilities, just like you can receive and parse JSON? That there's nothing stopping you from using a <table> to send tabular data, etc.? And that if you do so, then debugging your API becomes as simple as just visiting the same link the API client is visiting, and seeing the data rendered as HTML in your browser?

janci 4y ago
I'm not sure if you are agreeing with me or disagreeing. I was answering the original question - why has REST become non-REST: it is not suitable for client-server apps. >Compare and contrast: what SQL admin GUI clients do to discover the DBMS schema. They essentially spider it. Not really, there is information_shema where they get everything they need to know about structure separately from data. > Have you ever written a web scraper, for a site that doesn't really enjoy being scraped, and so uses stuff like CSRF protection "synchronizer tokens"? Yes. Awful. Do we want all APIs to be like that? Why? > It's right in the name: in HATEOAS, hypertext is the engine of application state. Hypertext as in, say, HTML. Fully agree on this one. Just that HTML is unsuitable for machine-to-machine communication, so it is not used for APIs.
- derefr 4y ago
  > Not really, there is information_shema where they get everything they need to know about structure separately from data. information_schema only includes standardized information about standard SQL features. It doesn't expose DBMS-specific features like PG's comments; let alone give you not-standardized info on things that are part of the standard, e.g. any DDL-equivalent machine-accessible representation for views or procedures or types or domains. Gathering all of that stuff requires carefully joining five or ten different DBMS-specific tables together. Some of it even requires feature negotiation + graceful degradation. > Yes. Awful. Do we want all APIs to be like that? Why? Because then everything other than the well-known root can be changed freely without breaking the client. Compare-and-contrast: remote object brokers in dynamic languages, e.g. Ruby's https://github.com/ruby/drb https://github.com/ruby/drb. There are module functions that serve as well-known roots to the APIs you're remoting against; but as soon as you get an object handle, everything from that point forward is the result of sending a proxy-object (opaque API) a message, and getting a handle to a new object passed back in return. Where that new object might actually be an object-handle to an object on a different system than the one you first connected to. If you write a client to talk to such a remote system the way it's intended (i.e. by making OOP-style call-chains, and holding onto object-handles you want to reuse), then there's very little that should be able to break your client library, besides a fundamental change in the semantics of what the remote service delivers. Your client library isn't making assumptions — it's being told what the possibilities are at each step, like a browser is/does. Also, the other thing you get is: anyone with a web browser can use your API, because your API is, in a certain sense, "a website." Like how anyone can interact with S3 by just visiting the URL of an object. > HTML is unsuitable for machine-to-machine communication Who said? Someone back in 2005, when every language in common use didn't have HTML-parsing libraries? HTML needs conventional microformats to specify the abstract types of otherwise-text data... but so does JSON. JSON gives you text and numbers, but it doesn't give you ADTs like you'd get from e.g. Avro / Protobufs / etc. You still need a schema on top of JSON to get anywhere. So what are you really getting from JSON that you don't get from having your XHR responses be HTML webpage that were designed to be highly machine legible?

by derefr 4y ago

janci 4y ago

I'm not sure if you are agreeing with me or disagreeing. I was answering the original question - why has REST become non-REST: it is not suitable for client-server apps. >Compare and contrast: what SQL admin GUI clients do to discover the DBMS schema. They essentially spider it. Not really, there is information_shema where they get everything they need to know about structure separately from data. > Have you ever written a web scraper, for a site that doesn't really enjoy being scraped, and so uses stuff like CSRF protection "synchronizer tokens"? Yes. Awful. Do we want all APIs to be like that? Why? > It's right in the name: in HATEOAS, hypertext is the engine of application state. Hypertext as in, say, HTML. Fully agree on this one. Just that HTML is unsuitable for machine-to-machine communication, so it is not used for APIs.

derefr 4y ago
> Not really, there is information_shema where they get everything they need to know about structure separately from data. information_schema only includes standardized information about standard SQL features. It doesn't expose DBMS-specific features like PG's comments; let alone give you not-standardized info on things that are part of the standard, e.g. any DDL-equivalent machine-accessible representation for views or procedures or types or domains. Gathering all of that stuff requires carefully joining five or ten different DBMS-specific tables together. Some of it even requires feature negotiation + graceful degradation. > Yes. Awful. Do we want all APIs to be like that? Why? Because then everything other than the well-known root can be changed freely without breaking the client. Compare-and-contrast: remote object brokers in dynamic languages, e.g. Ruby's https://github.com/ruby/drb https://github.com/ruby/drb. There are module functions that serve as well-known roots to the APIs you're remoting against; but as soon as you get an object handle, everything from that point forward is the result of sending a proxy-object (opaque API) a message, and getting a handle to a new object passed back in return. Where that new object might actually be an object-handle to an object on a different system than the one you first connected to. If you write a client to talk to such a remote system the way it's intended (i.e. by making OOP-style call-chains, and holding onto object-handles you want to reuse), then there's very little that should be able to break your client library, besides a fundamental change in the semantics of what the remote service delivers. Your client library isn't making assumptions — it's being told what the possibilities are at each step, like a browser is/does. Also, the other thing you get is: anyone with a web browser can use your API, because your API is, in a certain sense, "a website." Like how anyone can interact with S3 by just visiting the URL of an object. > HTML is unsuitable for machine-to-machine communication Who said? Someone back in 2005, when every language in common use didn't have HTML-parsing libraries? HTML needs conventional microformats to specify the abstract types of otherwise-text data... but so does JSON. JSON gives you text and numbers, but it doesn't give you ADTs like you'd get from e.g. Avro / Protobufs / etc. You still need a schema on top of JSON to get anywhere. So what are you really getting from JSON that you don't get from having your XHR responses be HTML webpage that were designed to be highly machine legible?