REST Considered Harmful

> The thing with REST, is that at its core, it's basically a RPC (Remote Procedure Call) that we've been trying to cram in the HTTP protocol. There is no good reason to do that. HTTP wasn't made for this, and we should instead be abstracting that layer away instead of trying to use it for purposes it's not meant to fulfill.

Yea, I'm gonna have to disagree with that statement. Things like OpenAPI have tried to solve the problem of having a generic format, but the problem is that in practice, apps/services are opinionated on how they structure data. For some this is a really good thing™, for example when an engineering group really thinks about their API design while for others, who haven't thought it through, this becomes a living nightmare for users of those APIs.

HTTP/REST are used (and will continue to be used) because they are ubiquitous. I would argue that 99.99999% of internet devices have the capability to speak REST. Whether that is curl in a shell script, javascript in a browser or python in an application... Nearly everything is capable of speaking REST, which I would actually argue is why a well thought out REST endpoint is a great solution for most applications.

There are "true" RPCs that do RPC really well/fast and when it makes sense to leverage those in your architecture you absolutely should. However, if it requires other developers to integrate with it, REST APIs are typically the way to go.

> My main issue with REST is that there are too many ways to pass arguments! Here is the list:

Well he even missed one, the headers. Eg, stripe uses a Stripe-Version header to select an API version

To reiterate what someone else already said: no, REST was never meant to be “just RPC”. If you want RPC over HTTP, use something like JSON-RPC rather than trying to invent it yourself; its creators have already solved many of the problems that you’re about to hit.

The term REST (short for Representational State Transfer) was defined by Roy Fielding in a dissertation in 2000. There are many ways in which REST is better suited for web APIs than the RPC model: some of them are about communication and meaning, some are about flexibility, but mostly they’re about working with the web as it already IS, with browsers and servers and caches and load balancers and a whole load of other complexity. The RPC model sounds simpler at first, and in many ways it is, but that simplicity can hit some major problems when you try to scale up beyond a handful of different clients and servers.

For a deeper summary, take a look at the Wikipedia page: https://en.wikipedia.org/wiki/Representational_state_transfe...

This short note seems to be based on the nowadays common misunderstanding that REST means doing RPC over HTTP with Json payloads. At least, according to the work that coined and defined the term REST -- REpresentational State Transfer --, it described an architectural style or pattern to overcome the inherent limitations of RPC. E.g. have a look at Chapter 6.5.2 of Roy Fielding, "Architectural Styles and the Design of Network-based Software Architectures" [1] to see that why it should not be an RPC mechanism:

  6.5.2 HTTP is not RPC

  People often mistakenly refer to HTTP as a remote procedure call (RPC) [23] mechanism simply 
  because it involves requests and responses. What distinguishes RPC from other forms of 
  network-based application communication is the notion of invoking a procedure on the remote machine,
  wherein the protocol identifies the procedure and passes it a fixed set of parameters, and then waits 
  for the answer to be supplied within a return message using the same interface. Remote method 
  invocation (RMI) is similar, except that the procedure is identified as an {object, method} tuple
  rather than a service procedure. Brokered RMI adds name service indirection and a few other tricks,
  but the interface is basically the same.

  What distinguishes HTTP from RPC isn't the syntax. It isn't even the different characteristics gained
  from using a stream as a parameter, though that helps to explain why existing RPC mechanisms were not
  usable for the Web. What makes HTTP significantly different from RPC is that the requests are directed
  to resources using a generic interface with standard semantics that can be interpreted by intermediaries 
  almost as well as by the machines that originate services. The result is an application that allows
  for layers of transformation and indirection that are independent of the information origin, which is
  very useful for an Internet-scale, multi-organization, anarchically scalable information system. RPC 
  mechanisms, in contrast, are defined in terms of language APIs, not network-based applications.

  The thing with REST, is that at its core, it's basically a RPC (Remote Procedure Call) that we've been
  trying to cram in the HTTP protocol.
  

One disadvantage of the proposed idea is that it will not cache very nicely at the HTTP level, ie. GETs that you would normally offload to a CDN.

Although it would be technically possible, I am not aware of any CDN that lets you cache based on the content of a multipart form.

Sounds like OP is making gRPC.