Do you have any resources showing what an API client for a "true REST" system would look like? The #1 objection I've seen to REST as Fielding described it is that it seems to basically assume that the human is the API client.
For example, this passage from Fielding:
> A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations.
The idea of a computer application that has no context beyond an entry URL and a media type (text/html) is pretty hard for me and many like me to wrap our heads around. I can't imagine a system being written that doesn't know what the options will be and what shape the data will come in, and once you've hard coded that it's not obvious what you gain by sending URLs instead of IDs.
I'm totally open to there being something I'm missing here, but every explanation of REST I've seen focuses exclusively on the shape of the server response and doesn't explain what an API client is supposed to do with the response and how REST avoids hard-coding client actions.
I wish I could have you look at a project I worked on in the early 2010s in the security industry. We had an architect who went full ham on HATEOS and honestly it was great. You could point a client at a single root endpoint and it would self-discover every other URL[path] it needed. We relied on RFCs where possible (sometimes drafts when an accepted RFC wasn't required). Everyone got very familiar with RFC 2616[1], link rels, uri templates[2], media types, &c.
It required architectural dedication because junior devs would complain that it didn't match what they learned about REST from webdev tutorials. Which is to say, the social hurdles to HATEOS implementations far outweigh the technical hurdles. They'd constantly try hardcode urls and have to be reminded not to do that by the backend folks. From the backend, it was great. We had tremendous flexibility when URLs weren't part of the spec and we were able to tackle hard problems like supporting multiple simultaneous versions quickly and with little lift because of this flexibility.
> Do you have any resources showing what an API client for a "true REST" system would look like?
You are using one, this very moment, as you read this comment. Fielding's concept of "REST" was not a prescription for a new type of RPC system; it was a description of the architecture of the web as it existed at the time. The "computer application that has no context beyond an entry URL and a media type" is simply a web browser.
Sure, but how is that a helpful concept in any way? If I started calling my operating system an "ALLOCBAG" and made a dissertation talking about "The ALLOCBAG Principle" you can't really deny me that it's a thing that exists ("ALLOCBAGs are all around you! You're using one I'd right now", I'd say), but it's not really advancing the state of discussion here.
Similarly, rebadging "a client/server system that does a thing when you interact with the client" as "REST" (yes, I know there's a bit more to the definition) doesn't seem useful or helpful. So out it goes, in favor of the one that's talking about a style of API design.
Roy Fielding designed the Adobe Experience Manager API according to his idea of REST [0]. I don't think the resulting API was remarkably noteworthy. [1]
Human UIs like HN are the only example I've ever seen that's compelling. But when you refer to it as a RESTful API (TFA uses "APIs" 31 times) you're not talking about a UI, you're talking about an Application Programming Interface, which is explicitly defined as an interface by which computers talk to each other.
If REST just plain shouldn't be used in APIs then that's a fine argument to make, but we should start calling for RESTful UIs and start pointing out that a RESTful API is an oxymoron. We shouldn't be pushing for integrating HATEOAS into APIs.
> Do you have any resources showing what an API client for a "true REST" system would look like? … The idea of a computer application that has no context beyond an entry URL and a media type (text/html) is pretty hard for me and many like me to wrap our heads around.
Here is a very, very simple one. It uses a hypermedia format which uses JSON syntax, but has more requirements in order to be valid:
The key is that this is a media type (let’s call it application/example+bank-account) which defines a particular object schema, which includes certain properties whose values must be URL strings (it uses HTML’s relative-URL rules).
> once you've hard coded that it's not obvious what you gain by sending URLs instead of IDs.
Well, for one thing the client does not need to care about constructing URLs because it just follows them. The logic is just ‘grab the value of a key, verify that it is a URL, follow it’ rather than ‘remember an ID, use some implicit knowledge to construct a URL, follow it.’ It means that the server is free to delegate certain accounts to other servers. It makes federation a ton easier. It means that application code is able to live at a higher level.
> The #1 objection I've seen to REST as Fielding described it is that it seems to basically assume that the human is the API client.
Reading the essay, it seems that is indeed the goal that the client is the human, so it would be weird for that to be an objection. If so, the objection then seems rather that a RESTful API is not terribly useful for a lot of systems.
Which is fine, not everyone has to love hamburgers either.
But yeah, I'd love to see a proper non-trivial example.
The essay repeatedly uses the phrase "RESTful API", so it's natural for people to get confused when it advocates for things that are fundamentally incompatible with an API client.
Imagine a RUST endpoint as a database interface. The various HTTP operations for record read, create/update, and delete.
The client could dynamically generate form formats which match the data type of records. You've probably used off the shelf CRUD software which behaves that way, only hard-coded based on settings.
For example, this passage from Fielding:
> A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations.
The idea of a computer application that has no context beyond an entry URL and a media type (text/html) is pretty hard for me and many like me to wrap our heads around. I can't imagine a system being written that doesn't know what the options will be and what shape the data will come in, and once you've hard coded that it's not obvious what you gain by sending URLs instead of IDs.
I'm totally open to there being something I'm missing here, but every explanation of REST I've seen focuses exclusively on the shape of the server response and doesn't explain what an API client is supposed to do with the response and how REST avoids hard-coding client actions.