3 ms·

Yes, the article is a good historical review, but like other “what is REST really” explanations, the example only works when an English-speaking human is the cl

by wrs 3y ago

Yes, the article is a good historical review, but like other “what is REST really” explanations, the example only works when an English-speaking human is the client. It doesn’t work as motivation for building APIs this way. A computer doesn’t know what the word “deposits” in that link means, unless the programmers on both ends agree on what it means. At that point it doesn’t look that different from agreeing on the possible values of “status” in the JSON. But wait, maybe we can just put ChatGPT on both ends and hope for the best… :)

agarren 3y ago
Can you elaborate on what you mean by "an English-speaking human is the client"? It seems to me that if the hypertext response in the example referenced "deposits" in Arabic, Swahili, English, or Japanese, it'd all be the same to the client. (fta) > 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. > The client would render this new HTML, totally unaware of what “overdraft” means or, indeed, even what a bank account is. So the client doesn't understand what a deposit is, but it doesn't have to. The response provides actions that the client knows how to incorporate and navigate. The alternative being a JSON response that is completely opaque - requiring additional parsing, explicit interpretation, and templating/interpolation, and DOM insertion before it's useful. A RESTful web client speaks hypertext. JSON-RPC is useful, but is not RESTful in the original sense of the word.
- wrs 3y ago
  This is exactly the confusion caused due to mismatched terminology. In the explanation the “client” is a browser. But obviously the browser isn’t an active participant in the exchange. The actual client of the banking service is the human looking at the browser. The human knows how to react because they know the English word “deposits” and can continue this game of adventure by interpreting whatever comes back, again based on English labels. Now consider how you’d write a script for a computer to use this “API” in automated fashion. Nobody creates a JSON-over-HTTP protocol because they think it’ll be easier for human clients to use. The area of controversy is how computers should talk to each other. Another way of saying this is that the concept of “self-describing” data is a handwave that is doing a huge amount of work here.
  - agarren 3y ago
    We're going to disagree, but respectfully, thank you for the discussion. > This is exactly the confusion caused due to mismatched terminology. In the explanation the "client" is a browser. But obviously the browser isn't an active participant in the exchange. The browser is also understood as a client in other similar exchanges [0]. There shouldn't be much confusion on the term, at least from a developer perspective. > The actual client of the banking service is the human looking at the browser. I don't see it this way. The article is clear about what the term "client" means (e.g., "a proper hypermedia client...", "...the client would render this new HTML...", "...the client must know how to interpret the status field...") It's also clear from Fielding's thesis itself, referenced in the article, what a "client" represents in its description of REST as a "client-server architecture" with hypermedia as a "client-server constraint" [1]. There is confusion about REST as a term. I don't believe it's due to mismatched terminology or a misunderstanding of the term "client" in the context of REST as a network/web architecture. > The human knows how to react because they know the English word "deposits" and can continue this game of adventure by interpreting whatever comes back, again based on English labels. The user of a (web) client isn't relevant in this case, nor is it how the user interprets what comes back. The point is that the (web) client can interpret a hypermedia response without any additional knowledge. The (web) client can make any additional actions available to the user without further interpreting the response as it would with the JSON version. > Now consider how you'd write a script for a computer to use this "API" in automated fashion. Now, your script is the client, not the browser, and your script is responsible for parsing the relevant data, following links, etc. How it works with RESTful responses and payloads is entirely up to your script. That said, it seems similar to a JSON response, you'll parse out the bits you care about and proceed accordingly. > ...The area of controversy is how computers should talk to each other. Another way of saying this is that the concept of "self-describing" data is a handwave that is doing a huge amount of work here. I disagree, but I can see where you're coming from. Machine-to-machine communication using hypermedia rather than JSON _still_ strikes me as "self-describing" in the sense that being able to locate, navigate, and act on the resources that hypermedia represents is what a "proper hypermedia client" is designed to do. You can still access the API programmatically, but now you have less parsing to do, and things like navigation and resource manipulation come for free. By that I mean there is no need for a dedicated API client that solely speaks the JSON-RPC dialect of the particular API you are accessing. (I'm thinking of "RESTful" API clients I've recently had to work with in one way or another: Box, BusinessCentral, Azure, DocuSign, etc.) I don't interpret "self-describing data" in the context of a network architecture to mean that the (web) client has attained enlightenment and suddenly knows what deposits and withdrawals are. There shouldn't be too much confusion on that point, even with the most superficial reading. Fielding describes "self-descriptive messages" as simply a RESTful constraint - not magic. You (through a [web] client) ask for deposits, and you receive a response containing details about a deposit and/or ways to manipulate those data further. How the user interprets the message, what they do with it, isn't interesting. What is interesting is that user will work with the resources through a web client: a RESTful web client can interact with a RESTful resource without additional "out-of-band" knowledge in the form of, say, JSON parsing and buckets of javascript imposing some RPC logic. [0] https://datatracker.ietf.org/doc/html/rfc6749#section-1.1 https://datatracker.ietf.org/doc/html/rfc6749#section-1.1 [1] https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_st...
paulddraper 3y ago
Accept-Language is a thing. It works just a well with HTML docs as with HTTP APIs. (i.e. usually not at all, but there you go)

by wrs 3y ago

agarren 3y ago

Can you elaborate on what you mean by "an English-speaking human is the client"? It seems to me that if the hypertext response in the example referenced "deposits" in Arabic, Swahili, English, or Japanese, it'd all be the same to the client. (fta) > 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. > The client would render this new HTML, totally unaware of what “overdraft” means or, indeed, even what a bank account is. So the client doesn't understand what a deposit is, but it doesn't have to. The response provides actions that the client knows how to incorporate and navigate. The alternative being a JSON response that is completely opaque - requiring additional parsing, explicit interpretation, and templating/interpolation, and DOM insertion before it's useful. A RESTful web client speaks hypertext. JSON-RPC is useful, but is not RESTful in the original sense of the word.

wrs 3y ago
This is exactly the confusion caused due to mismatched terminology. In the explanation the “client” is a browser. But obviously the browser isn’t an active participant in the exchange. The actual client of the banking service is the human looking at the browser. The human knows how to react because they know the English word “deposits” and can continue this game of adventure by interpreting whatever comes back, again based on English labels. Now consider how you’d write a script for a computer to use this “API” in automated fashion. Nobody creates a JSON-over-HTTP protocol because they think it’ll be easier for human clients to use. The area of controversy is how computers should talk to each other. Another way of saying this is that the concept of “self-describing” data is a handwave that is doing a huge amount of work here.
- agarren 3y ago
  We're going to disagree, but respectfully, thank you for the discussion. > This is exactly the confusion caused due to mismatched terminology. In the explanation the "client" is a browser. But obviously the browser isn't an active participant in the exchange. The browser is also understood as a client in other similar exchanges [0]. There shouldn't be much confusion on the term, at least from a developer perspective. > The actual client of the banking service is the human looking at the browser. I don't see it this way. The article is clear about what the term "client" means (e.g., "a proper hypermedia client...", "...the client would render this new HTML...", "...the client must know how to interpret the status field...") It's also clear from Fielding's thesis itself, referenced in the article, what a "client" represents in its description of REST as a "client-server architecture" with hypermedia as a "client-server constraint" [1]. There is confusion about REST as a term. I don't believe it's due to mismatched terminology or a misunderstanding of the term "client" in the context of REST as a network/web architecture. > The human knows how to react because they know the English word "deposits" and can continue this game of adventure by interpreting whatever comes back, again based on English labels. The user of a (web) client isn't relevant in this case, nor is it how the user interprets what comes back. The point is that the (web) client can interpret a hypermedia response without any additional knowledge. The (web) client can make any additional actions available to the user without further interpreting the response as it would with the JSON version. > Now consider how you'd write a script for a computer to use this "API" in automated fashion. Now, your script is the client, not the browser, and your script is responsible for parsing the relevant data, following links, etc. How it works with RESTful responses and payloads is entirely up to your script. That said, it seems similar to a JSON response, you'll parse out the bits you care about and proceed accordingly. > ...The area of controversy is how computers should talk to each other. Another way of saying this is that the concept of "self-describing" data is a handwave that is doing a huge amount of work here. I disagree, but I can see where you're coming from. Machine-to-machine communication using hypermedia rather than JSON _still_ strikes me as "self-describing" in the sense that being able to locate, navigate, and act on the resources that hypermedia represents is what a "proper hypermedia client" is designed to do. You can still access the API programmatically, but now you have less parsing to do, and things like navigation and resource manipulation come for free. By that I mean there is no need for a dedicated API client that solely speaks the JSON-RPC dialect of the particular API you are accessing. (I'm thinking of "RESTful" API clients I've recently had to work with in one way or another: Box, BusinessCentral, Azure, DocuSign, etc.) I don't interpret "self-describing data" in the context of a network architecture to mean that the (web) client has attained enlightenment and suddenly knows what deposits and withdrawals are. There shouldn't be too much confusion on that point, even with the most superficial reading. Fielding describes "self-descriptive messages" as simply a RESTful constraint - not magic. You (through a [web] client) ask for deposits, and you receive a response containing details about a deposit and/or ways to manipulate those data further. How the user interprets the message, what they do with it, isn't interesting. What is interesting is that user will work with the resources through a web client: a RESTful web client can interact with a RESTful resource without additional "out-of-band" knowledge in the form of, say, JSON parsing and buckets of javascript imposing some RPC logic. [0] https://datatracker.ietf.org/doc/html/rfc6749#section-1.1 https://datatracker.ietf.org/doc/html/rfc6749#section-1.1 [1] https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_st...

paulddraper 3y ago

Accept-Language is a thing. It works just a well with HTML docs as with HTTP APIs. (i.e. usually not at all, but there you go)