This article doesn't mention linking at all, which is at the heart of REST. Without links, it isn't REST, and most of the suggestions don't have anything to do with REST per se. Most of it is just standard JSON-over-HTTP stuff that's implemented in a variety of frameworks and libraries.
EDIT: To be clear, I don't particularly care if an API is "RESTful" or not, as long as it's well-designed and documented, but I think there are interesting/useful ideas in REST that are lost when it's conflated with JSON-over-HTTP.
> This article doesn't mention linking at all, which is at the heart of REST.
Please, just don't do it. Yes, I read the dissertation. It's just not a good idea, it has never given me any practical use whatsoever and has always made dealing with the API more annoying.
> Most of it is just standard JSON-over-HTTP stuff that's implemented in a variety of frameworks and libraries.
Yes, and we call that REST or RESTful anyway. We'll keep doing it that way. You're going to have to accept it.
You have to know how to parse the response. This usually requires to know what you will receive, which limits the usefulness of generic link responses somehow
The main problem with REST is that it never developed tools even on the level with what we have for GraphQL.
Somehow everyone rushed to implement GraphQL schemas, and no one rushed to implement JSON Schemas for example. And JSON Schemas with the right tools are a much more powerful instrument.
Same goes for linking, and the rest of HATEOAS.
At a company I worked we had an internal tool built for most of this stuff which took a lot of problems with HATEOAS away. Unfortunately, we never opensourced it :(
> The main problem with REST is that it never developed tools even on the level with what we have for GraphQL.
REST isn't really designed for the problem of implementing a single, centrally controlled API, and is basically overkill for that. Its made for a decentralized, heterogenous network of resources controlled by different parties, which can have separately evolving relationships. Like, say, the WWW.
If you have sufficient tooling around it to consume that kind of heterogenous resource network, it's trivial to apply it to a centralized service, but we don't really have the kind of client tooling for applications other than UIs that makes that nice widely available yet, and everyone wanting walled silos instead of free remixing means that REST is probably an antifeature for lots of API providers even if the tooling was 100% there.
> Please, just don't do it. Yes, I read the dissertation. It's just not a good idea, it has never given me any practical use whatsoever and has always made dealing with the API more annoying.
If you believe REST is not a good idea then you never had to deal with versioning and struggling to keep clients and servers you don't own to play nice. Asserting that something like REST has no practical purpose is asserting that your experience is slim to none in this domain so that you are not mindful of the most basic challenges of getting servers and clients that evolve independently to continue to interoperate with minimal development effort. REST is content discovery and allowing clients to transparently adapt to breaking changes in the server. How does anyone with any relevant experience miss the point of that?
Furthermore, your assertion makes no sense at all. The main property, and the whole point, of REST is HATEOAS. It makes absolutely no sense to claim an API is REST if it misses the single most important design element that's behind REST. This is not pedantry or nit-picking: it's the whole difference between plain old RPC and REST. If you want to design an API that provides fixed endpoints to be called,and isn't discoverable or navigable, then just call the spade a spade: RPC over HTTP. Otherwise why do you feel the need to claim you design an API around a design principle you don't use and even criticize?
>If you believe REST is not a good idea then you never had to deal with versioning and struggling to keep clients and servers you don't own to play nice.
Sincere question: how does HATEOAS helps with this?
The only thing that HATEOAS helps with, is when the URL pointing to an entity changes, which is the most simplest change someone can make to its API.
But if an API ever changes the relationships between entities (new entities, 1-1 relationship changed to a 1-m relationship, ...) then HATEOAS won't help at all. You'll still need to change the logic of your client to take into account the modifications.
I've always felt like nobody bothered supporting HATEOAS because it's practically useless. The only use-case where it can be used is if you want your API to be crawled by a search engine. Then the search engine could crawl between entities thanks to the links you provide.
> Sincere question: how does HATEOAS helps with this?
The whole point of HATEOAS is to address this. This is pretty much why it was developed and presented. Why on earth is anyone discussing REST not picking up on it's reason to exist?
> The only thing that HATEOAS helps with, is when the URL pointing to an entity changes, which is the most simplest change someone can make to its API.
It really isn't. At all. You're somehow missing the whole point of a resource-based architecture, let alone REST.
The whole point is that there are no fixed paths. At all. All there is is resources, whose representation might vary in shape and form, which are made to be discoverable by providing semantic descriptions of said resources. With REST you provide resources and metadata that points to representations of those resources. With REST your clients do not care about endpoints other than a root one, and resources. The resto of the process consists of tracking resource representations that you want, and you do not care where they are. At all.
This sort of profound misconception of what REST is supposed to be is the reason why somehow some people believe that it's reasonable to slap the REST label on APIs just because they churn out JSON. You can't. REST is based on design constraints that address a problem which these APIs fail to address at a fundamental level.
> Sincere question: how does HATEOAS helps with this?
HATEOAS basically involves two main things:
1. Resource representation specifications are communicated in the communication channel (in HTTP, this can be a combination of MIME type in headers are more specific specification in the document itself for responses, and accepts header in requests.)
2. Related resources are identified by URL.
> The only thing that HATEOAS helps with, is when the URL pointing to an entity changes
False, though #2 helps with that.
> But if an API ever changes the relationships between entities (new entities, 1-1 relationship changed to a 1-m relationship, ...) then HATEOAS won't help at all.
No, that's what #1 helps with, as it provides the means where you can:
(1) identify the resource representations available,
(2) identify if you have a resource-consumption/creation-client available that satisfies the endpoint requirements, and
(3) select the correct client implementation.
> You'll still need to change the logic of your client to take into account the modifications.
Yes, someone needs to implement a new resource client if a new resource structure, or representation of the same structure, is developed.
And if you are doing a single, centralized API, where no one else will be hosting something using the same resources, REST doesn't provide much. Where REST shines (which is why it is abundantly used on the web) is where large numbers of different parties will be hosting services using a potentially shared set of resource representations, where each hosts may evolve the particular set in use on their own schedule, and perhaps even using different network protocols, and you don't want to have bespoke clients for each service, but instead protocol clients for each network protocol and resource clients for each resource representation, and in-band signalling of not only where to get each resource once you get to an entry point, but also have the network protocol client you need and the resource client you need to successfully carry out each transaction.
I'm totally fine with calling it RPC-over-HTTP, or RESTless, or unREST. I'm also fine with just calling it REST. I don't care.
I'm not fine with making an API use HATEOAS, especially not for the sake of being pedantically accurate about the word REST.
As for your defense of HATEOAS, you're not doing a good job. If it's such a good idea, why is pretty much nobody doing it as intended? How exactly does it help with versioning? Can you describe a real use case?
The way I see it, if you want to break your API, slap /v2 in front of it. Otherwise, I strongly suggest that you do not break your API. Do not move stuff around pointlessly. I guarantee you that even if you followed HATEOAS best practices to the letter, your clients are still going to break. You don't want that.
This is a semantic dispute. Our disagreement is on whether this is a dispute worth arguing over.
There are many other industry buzzwords like "object oriented" that don't match up with what the people who coined the term had in mind. It's a nuisance, but nothing to get worked up over.
No, a truly RESTless API must do away with all the other pointless HTTPisms in REST. If you're using any other method than GET or POST, or any other codes than 400 and 200, you're not truly RESTless.
Most of the times I end up with put endpoints with verbs, because that often how businesses work. Objects and processes. Behind a REST resource there is a database table most in of the cases. But what if I want to send an email? POST /emails ? That's RESTless as well!
I wrote about why linking is useful recently https://www.daniellittle.dev/practical-hypermedia-controls. I've been using Hypermedia in my APIs for a few years now and it's been so useful for making great APIs. One of the things I really love about it is that you can test/use the API directly much more easily, because the knowledge about how to use it is in the API itself, instead of half hardcoded into the client.
EDIT: To be clear, I don't particularly care if an API is "RESTful" or not, as long as it's well-designed and documented, but I think there are interesting/useful ideas in REST that are lost when it's conflated with JSON-over-HTTP.