4 ms·

The Atlassian APIs have JSON responses with URL links throughout for further navigation. That would seem like it satisfies the stricter definition of REST witho

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.

fatnoah 3y ago
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.
pmontra 3y ago
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.
- Jasper_ 3y ago
  HTTP already has a method for redirecting the client if they use an out of date URL. Three of them, in fact.
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.

fatnoah 3y ago

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.

pmontra 3y ago

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.

Jasper_ 3y ago
HTTP already has a method for redirecting the client if they use an out of date URL. Three of them, in fact.

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.