Who Cares about GET vs. POST? NoREST

You've made everything non-destructive in your example, which I think makes REST a better fit - although even then, note how your example requests are almost all GET or POST.

> does not conform to REST best practices because POST is for creating new records -- immediately the developer is confused

You've got it backwards. The developer doesn't start with that request and try to figure out what it does. The developer starts by wanting to e.g. convert an image to gif, and trying to figure out what call will let them do that.

    POST /image/  -> 200 OK, { id: 2 }
    PUT /image/2  -> 200 OK

Notice how you're offering the same operation through two different verbs here - exactly what the article is advocating!

The specific domain where I've seen REST go most wrong is contracts for large scale commercial insurance / reinsurance. Operations are things like:

* Split a contract into multiple loss layers (0-25%, 25%-50% etc.) * Reshuffle the contract hierarchy - e.g. change a ship insurance contract from being split into hull / cargo and then individually layered in them, to being split into layers and then each of those split hull / cargo * Compare two quotes, potentially made against different versions of the contract

All these are things you can encode as REST operations - you can think of particular things to be entities and declare each of these to be creating or deleting entities. But that's in the same sense that you can encode any data as binary. What we found was that users - people with actual domain knowledge - didn't think in terms of those entities. They thought in terms of these operations, which had their own names that everyone in the industry understood, and the only entity they thought of was the single "current version of the contract" - everything else was one of several different kinds of "change the contract" operation. So the only mapping that made sense to a client familiar with the domain was a bunch of different POST operations on a contract object.

Why you use GET vs POST are conventions. There are no way to enforce any rules in web services and conventions help to make the things you are looking at recognizable. And conventions do change over time. I think we need more HTTP verbs like START and STOP and I wish POST was NEW. Merge vs. update-all for PUT is still not well established and now we have PATCH. Such terrible names. I would love something like REPLACE and MERGE or something more descriptive.

I also think that your customer order example could have been done better. Something like

Your example: OrderDTO Customer::GetOrder(int customerID, int orderID) But that's the wrong side of the equation, that's the definition of the function. If you call the function it would look like this: GetOrder(myCustomerID, myOrderID)

And an equivalent REST call would look like this with a little clean up. GET /orders/?id={id}&customer-id={customer-id}

Doesn't look that much different to me. Sure you could have done GET /orders/{id}/?customer-id={customer-id}, but there is no reason why the above is wrong from a RESTful perspective. Why would you marshall a whole JSON payload to do a simple GET? You are not creating a tuple to pass the two parameters in your full-language function example, what's the reason it is required for the RESTful call?

As I mentioned above HTTP needs a couple more verbs and aliases for the existing verbs. You think of situations like:

START /timers STOP /trains

A lot of the time we jam POST and PUT in this situation and they are poor substitutes for a larger verb vocabulary. I have built a few automation projects and any actions you do can usually fit into

NEW GET UPDATE (merge) DELETE START STOP OPEN CLOSE

still limited, but pretty good at covering almost all the verbs needed. You supply the nouns.

NEW /vms START /vms OPEN /remote-desktop/1234 CLOSE /files/folder/path/to/file

Especially with persistent connections in HTTP2 and web sockets and things of the kind OPEN and CLOSE will likely be need to establish these kinds of connections. You could probably get away with using START and STOP though, such as:

START /remote-desktop/?computer=1234

As for HTTP error codes. They need an overhaul. 404 and 403 do the job fine, but giving the user an idea of whether their JSON was malformed (Syntax) vs. the data in the payload was invalid is difficult to distinguish with just 400. But the return payload should describe the error in detail. Not many conventions there to help.

As for HATEOS, I used to think it was great, but I am meh on it now. It needs refinement.

"Does any language force you to prefix a function with 4 verbs?"

Actually, I don't really know. But for sure HTTP isn't forcing you to only use GET/POST/PUT/DELETE, even if this verbs are usually enough to design your API. It's quite funny to hear some people (I'm not talking about the author) joking about the "418 I'm a teapot" response status, which is defined in a HTTP extension, and then telling you that having only 4 methods to design an API is too restrictive.

HTTP is extensible, so why misusing it?