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