Yes most things are crud if you zoom out enough that doesn’t mean REST is just fine. The scope is larger now, the states are more complex and interrelated, relationships are more complex, data privacy laws can affect the physical implementation. REST also has a lot of baggage that leads to excessive bike shedding, or refusal to allow useful endpoints that aren’t sufficiently restful. Proponents also tend to be more concerned with the purity of the api than the usability and effectiveness of it
Yes, there are certain things that don’t map to key principles of REST, and I have upon occasion see people way too hooked on purity of REST for any practical end.
However, to the extent that you at least consider how it could map, then that’s helpful.
If you say “you can’t have an application error, you must ONLY use HTTP error codes”, that would be bogus. But if your application knows it has an error, why not also set HTTP status code to indicate an error as well? You have to set a status code anyway, might as well at least get the first digit right, or just 500 == error, 200 ==OK if you don’t want to hash out 4XX v. 5XX.
REST may not be sufficient, but that doesn’t mean it’s helpful to actively work against the HTTP semantics when they could be a vague indicator consistent with your API.
There’s also value in treating http as just a transport later. It can give you clear boundaries, 200 the app processed the request, anything else the app didn’t process it.
But what is the value of a 200 OK when the request absolutely failed? As a caller, I don’t care that it successfully was conveyed but still utterly failed. Depending on my usage, I may only care about pass/ fail and the backend insisting I have to handle multiple different ways of expressing failure is just more work with no value.
Using 500 does nothing to preclude your application errors. If the caller wants nuance, it can still have it in the body or headers.
refusal to allow useful endpoints that aren’t sufficiently restful
And there are good reasons for that, GraphQL-like endpoints seem great to use, but are often a bad idea. The more freedom is given through an API, the less guarantees one can deliver. Security, scalability, and maintainability all become more difficult for APIs with endpoints that attempt to do several things at once.
But most importantly, REST doesn’t tell you exactly how to build your endpoints, as long as they’re stateless, cacheable, and refer to system resources with enough context to allow their direct manipulation.
These are good principles for older and modern web apps, that hasn’t changed. In fact, one can argue that the larger and more complex the system the more important it is to simplify its endpoints. And you can build pretty complex systems while following these criteria.
Fully agree, purity of REST is dubious, but a ‘REST-as-possible’ absolutely is helpful to keep people from going way of the rails in ways that annoy external consumers of their API. One API I dealt with claimed to be ‘REST’ but basically everything you did was ‘Create a Task’, ‘Get Task’. No modeling of state other than the state of remote function calls, which might have been nice for them but now I have to lean what tasks are possible and how to create them when a more REST like hierarchy would have been a bit closer to ‘self documenting’.
This is why I’m not a fan of REST, the whole as possible part is meaningless. It could be an api that’s 99% REST with a few well thought out methods for common actions that aren’t quite REST, or it could be a mess of an api that uses PUT occasionally.
Self documenting at an application api level is not really possible. What I’d rather have is consistency and predictability, which is impossible in a REST as possible system.
For people with Linux experience, I point to sys and proc as examples of some of the best principles of “REST” in play. You can get far exploring it and if nothing else it gives you some good discoverable clues for searching what you want.
Proxmox did something similarly nice by publishing a lot of their model via a fuse filesystem.
Imitating a filesystem like interface is a useful approach, and “REST” is the closest buzzy things to get people on that page.
Yes most things are crud if you zoom out enough that doesn’t mean REST is just fine. The scope is larger now, the states are more complex and interrelated, relationships are more complex, data privacy laws can affect the physical implementation. REST also has a lot of baggage that leads to excessive bike shedding, or refusal to allow useful endpoints that aren’t sufficiently restful. Proponents also tend to be more concerned with the purity of the api than the usability and effectiveness of it
Yes, there are certain things that don’t map to key principles of REST, and I have upon occasion see people way too hooked on purity of REST for any practical end.
However, to the extent that you at least consider how it could map, then that’s helpful.
If you say “you can’t have an application error, you must ONLY use HTTP error codes”, that would be bogus. But if your application knows it has an error, why not also set HTTP status code to indicate an error as well? You have to set a status code anyway, might as well at least get the first digit right, or just 500 == error, 200 ==OK if you don’t want to hash out 4XX v. 5XX.
REST may not be sufficient, but that doesn’t mean it’s helpful to actively work against the HTTP semantics when they could be a vague indicator consistent with your API.
There’s also value in treating http as just a transport later. It can give you clear boundaries, 200 the app processed the request, anything else the app didn’t process it.
But what is the value of a 200 OK when the request absolutely failed? As a caller, I don’t care that it successfully was conveyed but still utterly failed. Depending on my usage, I may only care about pass/ fail and the backend insisting I have to handle multiple different ways of expressing failure is just more work with no value.
Using 500 does nothing to preclude your application errors. If the caller wants nuance, it can still have it in the body or headers.
And there are good reasons for that, GraphQL-like endpoints seem great to use, but are often a bad idea. The more freedom is given through an API, the less guarantees one can deliver. Security, scalability, and maintainability all become more difficult for APIs with endpoints that attempt to do several things at once.
But most importantly, REST doesn’t tell you exactly how to build your endpoints, as long as they’re stateless, cacheable, and refer to system resources with enough context to allow their direct manipulation.
These are good principles for older and modern web apps, that hasn’t changed. In fact, one can argue that the larger and more complex the system the more important it is to simplify its endpoints. And you can build pretty complex systems while following these criteria.
Fully agree, purity of REST is dubious, but a ‘REST-as-possible’ absolutely is helpful to keep people from going way of the rails in ways that annoy external consumers of their API. One API I dealt with claimed to be ‘REST’ but basically everything you did was ‘Create a Task’, ‘Get Task’. No modeling of state other than the state of remote function calls, which might have been nice for them but now I have to lean what tasks are possible and how to create them when a more REST like hierarchy would have been a bit closer to ‘self documenting’.
This is why I’m not a fan of REST, the whole as possible part is meaningless. It could be an api that’s 99% REST with a few well thought out methods for common actions that aren’t quite REST, or it could be a mess of an api that uses PUT occasionally.
Self documenting at an application api level is not really possible. What I’d rather have is consistency and predictability, which is impossible in a REST as possible system.
For people with Linux experience, I point to sys and proc as examples of some of the best principles of “REST” in play. You can get far exploring it and if nothing else it gives you some good discoverable clues for searching what you want.
Proxmox did something similarly nice by publishing a lot of their model via a fuse filesystem.
Imitating a filesystem like interface is a useful approach, and “REST” is the closest buzzy things to get people on that page.