The Atlassian APIs have JSON responses with URL links throughout for further navigation. That would seem like it satisfies the stricter definition of REST without being HTML. But self-describing interfaces like that are only useful when interacting with people who are then deciding what next action to take. They are decidedly not what you want when interacting with programs where the semantic interpretation of information is hard-coded into the program.
That's why at the same time, REST was taken as a call to action to formalize the server-side API that clients rely on so that your user-facing UI would use that API to generate the relevant HTML for the browser and the same API could be reused for 3p developers to rely on to build automation / additional products without increasing the maintenance area.
Agree. I've built a bunch of stuff using those APIs and consuming those links is actually more work than not having them, IMHO. To find them, I have to look at response payloads, identify the field with the link, and then call that link to get additional details. A simple, documented resource to URL mapping would be easier to use. It comes at the cost of having to update code when resource locations change, but I've yet to see that happen outside of major API changes that break things in other ways that require code changes on my end.
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… :)
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.
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'.
I had to deal with one of those APIs in a project years ago and we did use the URLs that it sent us in the JSON responses. We could have hardcoded them but that would have made our client brittle, because it would fail anytime the devs of the server changed their mind on their endpoints.
This means that an attack on that server could make us POST to or GET from another domain controlled by the attacker? Absolutely yes. I don't remember how we dealt with it. Maybe we fixed the host, or made some sanity checks. Anyway an attacker with that level of access could probably siphon out data in a less evident way.
That's why at the same time, REST was taken as a call to action to formalize the server-side API that clients rely on so that your user-facing UI would use that API to generate the relevant HTML for the browser and the same API could be reused for 3p developers to rely on to build automation / additional products without increasing the maintenance area.