How Did REST Come to Mean the Opposite of REST? (2022)

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 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.

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.

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.

1. https://www.rfc-editor.org/rfc/rfc2616

2. https://www.rfc-editor.org/rfc/rfc6570

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:

    {
        "account_number": 12345,
        "balance": {
            "currency": "usd",
            "value": 100.00
        },
        "status": "good",
        "deposits": "/accounts/12345/deposits",
        "withdrawals": "/accounts/12345/withdrawals",
        "transfers": "/accounts/12345/transfers",
        "close-requests": "/accounts/12345/close-requests"
    }

> 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 notion of an optional constraint may seem like an oxymoron. However, it does have a purpose in the architectural design of a system that encompasses multiple organizational boundaries. It means that the architecture only gains the benefit (and suffers the disadvantages) of the optional constraints when they are known to be in effect for some realm of the overall system. For example, if all of the client software within an organization is known to support Java applets [45], then services within that organization can be constructed such that they gain the benefit of enhanced functionality via downloadable Java classes. At the same time, however, the organization's firewall may prevent the transfer of Java applets from external sources, and thus to the rest of the Web it will appear as if those clients do not support code-on-demand. An optional constraint allows us to design an architecture that supports the desired behavior in the general case, but with the understanding that it may be disabled within some contexts.

I think this means you only do it when it makes sense. Perhaps this is too open-ended as you can run basically anything on the client, including a full application. But I think the stateless requirement means you should not require that the server be bothered with the client state, and that the client state should be easily recoverable from the resource URI. But I don't actually know. You don't have to commit to using REST principles if you don't want to. I think it was proposed as a way to reduce server load and bugs, not as a way of life.

Cookies are stateless though, that's the whole point of cookies.

(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.

It works just a well with HTML docs as with HTTP APIs.

(i.e. usually not at all, but there you go)

Here’s how HATEOAS is supposed to be helpful for computers:

1. Out of band, humans create complex, useful, well defined media types that cover the space of the functionality they’re trying to define. These need to be well documented. This is where the whole thing falls down

2. Once you’ve got useful media types, you build servers that offer clients a “service document”, a collection of interesting resources (with resources potentially exposed with different media type representations, so newer better media types can be chosen when they’re created in the future, without needing to swap out your server)

3. Servers also define a variety of useful verbs they support, which can also expand over time

REST depends heavily on (1). Since almost no one bothers to do (1), the whole project gets tarnished by people trying to do the later stuff and calling it REST.

Don’t worry, it’s not. While some hypermedia is intended for humans, there is no reason a hypermedia might not be targeted at computers instead.

For example, and I've been guilty of this too, in data science, it's common for tutorials and examples to be use ipython/jupyter notebooks. This, however, should not be mistaken for "It's a good idea to use notebooks as part of the code-to-production pipeline." It's an easy mistake to make, and implicitly part of how AI/ML is taught.