Do you really know why you prefer REST over RPC?

It seems to be that many of the comments on this and other API posts recently are by people who have never had to integrate with some else's "mostly REST but only when it suits me" API.

If the API you are writing has these features:

* you are the consumer as well as the author.

* no other developer is ever going to need to understand it.

* don't care about server/proxy/library support.

by all means don't bother with REST.

But if you are doing one/some/all of the above implementing a HTTP REST architecture is going to make your life and fellow developer's lives easier. That is what specifications are for, there to make things easier for everyone.

The thing I find most frustrating about these discussions is REST is such a simple architecture with a well thought out technical reasoning. Yet people happily ignore parts of it because of some unstated preference, and develop their own architecture which other developers then have to divine.

> The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload.

So PUT either creates or replaces a resource.

Definition of replaced:

> 1. take the place of.

Source: https://www.google.com.au/search?q=define%3A+replaced

It is pretty clear to me that the spec says PUT completely replaces the state of a resource. So not just a convention but what the spec says.

BUT lets take it further. Lets say you do allow partial updates with a PUT. Can you guarantee that your resource's state will always be internally consistent?

Say you have two clients, both doing partial PUTs and do the following:

    Client 1: GET /foo
    Client 2: GET /foo
    Client 1: PUT /foo {'bar': 1}
    Client 2: PUT /foo {'baz': 2}

Is the foo resource is a consistent state? For some applications it could be but for many it won't be. And worse for some applications it may not be idempotent and a client's proxy is going to silently retry a PUT that isn't safe to do so.

So by allowing partial PUTs we're requiring the developer to consider all combinations a resource could be updated. They then need to communicate the valid combinations to any clients.

OR they can split the resource up finer grained resources, each one representing a valid PUT.

the problem with HTTP REST verbs is that not everything can be (or should be) represented as a resource.

a simple example is a one-click payment + order action. you're creating multiple records in different tables - payment gateway transaction log, payment table, an order table, probably creating a customer record, sending email notification, logging a conversion, etc.

that sequence of actions does not adhere neatly to any HTTP verbs. it can be more clearly called "processorder" because it involves a lot more than creating an order record in a table. if you'd like, you can of course do POST /orders, but the nuance of what's happening is unnecessarily lost.

another example is a taking that order and marking it as "shipped". it is not a simple PATCH /orders/123 shipped=true. the front-end does not know all the fields that must be set in all the places on the backend. it is in fact a series of actions that take some data from the front, and some from the back and do a bunch of things that represent the setShipped() sequence.

HTTP verbs were designed for managing documents, for which they work well. They also happen to map well for direct db entries via CRUD. but trying to shoehorn them into all aspects of complex web apps is misguided. a true RPC is often what is necessary.

"Buy this" might create multiple records in different tables, but there is no requirement that one URL in a REST API corresponds directly to one record or one table. The REST API does not have to expose the entire sequence of under-the-hood actions. This does not somehow require RPC to address.

This is purely focusing on it from the API level. REST is an architectural style. This comparison seems like it is entirely missing the point.