This is the start of an article we might want to put on open-rpc.org, or somewhere, just putting it here to reference, possibly PR soon.
REST over HTTP is over. Long Live REST.
What is REST?
REST is a set of architectural guidelines for building APIs. It prescribes having resources as the interface for APIs and contains links pointing to relative resources to fetch additional information.
REST tied to HTTP is good, until its not
REST offers an ambiguous approach for API design, it's not a contract, not a specification, and not a reproducible process. It does contain HATEOS for specifying related resources, but only available at runtime.
REST over HTTP leaks protocol details (headers + url + body + status code + success/failure) into the application layer. This tight coupling limits its usefulness in modern production systems that want to provide an API with a wide array of transports like HTTP, HTTP2, Websocket, IPC, MQTT, etc.
There is no batching support for REST HTTP APIs out of the box. This leads to things like denormalizing the data and leaking it into other resources to cut down on expensive HTTP calls.
CRUD, then what?
Starting with CRUD(Create Read Update Destroy) and tying those to methods (GET PUT POST DELETE) lays out a simple design approach but adding complexity can end up in creating one-off, non-intuitive resources that only loosely relate to another.
HTTP Status Codes
Not only do status codes leak into the application layer, but they are relied on for errors. Application level errors map to 4xx error codes, except when they don't, like with a 404.
Failed x? 400 Bad Request.
Failed y? 418 I'm a teapot.
Can't find a resource? 404 Not found.
Success codes are also inconsistent; the status code for creating with POST is 201, unless it will return content, then the status code is 200.
OpenAPI/swagger exists to provide documentation and interface definition, but it famously does not follow REST, furthering the move away from REST API design.