Who Cares about GET vs. POST? NoREST

In my opinion REST is fat more easier to understand for non-CRUD resources. The whole idea of CRUD makes REST sometimes seem like an HTTP adapter to the database.

However, when you move beyond these simple examples and start trying to build a REST API for a messy, complex system, you immediately run into trouble. How do you deal with non-CRUD operations? How do you deal with long running processes?

You POST the work to be done to a resource. That resource returns a URL where you can follow the state of the long running process. An alternative would be to provide a Webhook that will be called when the long running process has finished.

Or entities in an indeterminate state?

Same principle, return its actual state on a GET request (polling). Or use a Webhook (push).

How do you aggregate multiple resources into individual request/responses for performance?

Use HAL embedding or multipart.

How do you de-duplicate identical entities within an aggregated response?

Use the hypertext caching pattern in your caching layer or proxy. Use the URL as a unique key.

How do you return only particular fields?

Use HAL embedding, query parameters or a subresource.

How do you handle paging and filtering?

Use link relations and query parameters.

How do you handle transactions?

That's exactly what POST is for.

How do you handle authentication and security restrictions?

Provide a token header over https. Avoid magic URLs based on cookie state (i.e. even when you are logged in as mike your account details still are at https://example.org/user/mike/account). Restrictions are a product of the token and the requested URL.

All of these things can be solved, but by the time you've finished, your API will be far from easy to understand.

That is true, it won't be easy to understand, but it will be simple, composable, discoverabe and scalable.

It will need a load of accompanying documentation to make it usable

In my experience the opposite is true, true REST (which includes hypermedia controls) need less accompanying documentation. It makes resources more predictable and less dependendent on URLs.

All of these things can be solved, but by the time you've finished, your API will be far from easy to understand. It will need a load of accompanying documentation to make it usable, and will have a bunch of weird corners where you're initiating operations as a side effect of setting entity flags, or you've noun-ed verbs in order to turn an abstract operation into a resource. E.g. PUT /server-reboot-attempt.

In stead of making a separate resource for every action it would suffice to make one that receives actions by POSTing to it. You can respond with a URL that represents its progress. And it will also save a lot of unnecessary links or hardcoded URLs.

It's just that, for some reason, when you shift to imagining a robot interacting with your site rather than a person, people get confused.

Though, really, I know that the reason is that they're trying to shoehorn an existing set of APIs into this cool REST thing they've heard about. In reality, you need to look at it from the other direction. Or, don't try wrestling with REST.