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.
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.
> The (web) client can make any additional actions available to the user without further interpreting the response as it would with the JSON version.
What happens when there is no user and it's fully automated? Everywhere in the post where you say "you", you're referring to an intelligent user interacting with the website which is the point being made - hypermedia REST works well in an interactive context, but an automated context needs something simpler, more reliable, & more parseably stable than the more mutable UX you'd send the user. The point is that this breaks down when you have automation interacting with a service that has no concept of agency - it's executing specific sets of functions against endpoints and discovery is not particularly relevant as that discovery happens once when the programmer writes the automation code.
That's the point of the article; when you say 'an automated context needs something simpler, more reliable, & more parseably stable', you are referring to an RPC system like, eg, JSON-RPC. This is what the OP article calls 'the opposite of REST'.
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.