Who Cares about GET vs. POST? NoREST

Is it just me or GET /customer/33245/order/8769 is wrong You have unique order id... then use it GET /order/8769 like that ??

Just require query string to be sorted. In Python:

  urllib.urlencode(sorted(params.items()))

Most, but not all, "REST" APIs (other than the web) violate at least one element of the definition of REST, most commonly they don't actually implement HATEOAS, requiring out of band knowledge of applicable resource URIs or URI patterns and/or information about data formats not communicated by documentation of media types and hypertext relations.

But that's because REST is often used as a buzzword by people who don't know what the architectural style entails, or aspirationally to describe one goal of the design of an API, but one that may be compromised for conflicting goals.

Maybe it would make sense if you actually looked at it like a domain.

I'm not sure of a domain where an operation cannot be represented as one of:

* Return $data

* Return a manipulation of $data that is the same type as $data

* Return a value derived from $data

* Update $data with a new value

* Create a new identifier with values that conform to the same type as $data

* Delete $data from the system

Certainly there are things like transcoding a streaming video which don't seem to map immediately, but they could if you shoehorned them. You're probably better off using something like UDP for that, though, instead of an HTTP request over TCP/IP.

Let's take images. Translation factor:

    worzworts -> image (identity)
    flubbleize -> encode to jpeg (non destructive manipulation)
    mrefgle -> encode to png (non destructive manipulation)
    chezzle -> execute image as a Piet program and return the output (derived value that is not necessarily of the same type)

Now, it's think through it a little.

    POST /image/  => 1

    GET /image/1 -> identical response (except some http headers) to the imgur URL

    GET /image/1/piet -> "Piet"

    GET /image/1/jpeg -> /image/1 re-encoded as a jpeg

All good here. But let's look at some of the operations you suggest might be used, and the action they take:

    POST /image/1/jpeg -> re-encodes the gif as a jpeg and saves it to /image/1; does not conform to REST best practices because POST is for creating new records -- immediately the developer is confused

    GET /image/1/piet ->  because jpeg encoding is lossy, it fundamentally changes the data source at /image/1 with an arbitrary filter; in this case, JPEG compression.

Funky undefined behavior, and it may not have the side effects intended. Now let's see how it would work RESTfully:

    GET /image/1/jpeg -> returns a jpeg encoding of /image/1

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

    POST /image/ "Piet" -> Error 415 (images expect an image, not a string)

    GET /image/2 -> returns jpeg encoding of /image/1

    GET /image/1/piet -> "Piet"

    PUT /image/2  -> 200 OK

    GET /image/2/piet -> "Piet" (since png is a lossless encoding, Piet will perform the same on it)

If you conform your API to single responsibilities, you won't confuse the consumers of it by transforming a data source in-place on their request.

Things go a little sideways, but not much, if these operations need parameters. But that's why they're query parameters and not a part of the url. I don't think anyone would suggest that you create a URL like

    /image/1/jpeg/width/640/height/480

That's just silly. If you follow the single-resource-deep philosophy, though, anything after the ID is a resource that is derived from the resource residing at #ID. This URL might actually make a lot of sense:

    /image/1/jpeg/resize/640x480

But then again, so would:

    /image/1/resize/640x480/jpeg

But wait, there's an even better way to define these ... and still be restful.

    /image/1.jpeg, /image/1.png, /image/1.piet

Oops, that last one doesn't work. Piet isn't an image format, it's the result of executing the image as a Piet program. So maybe that one works better as a URL segment:

    /image/1.jpeg (image), /image/1.png (image), /image/1/piet (string)

In this case,

    /image/1.jpeg?w=640&h=480

makes just as much sense as

    /image/1.png?w=640&h=480

But since we know that instead of a transformed image, the image/:id/piet resource is a derived string based on image/:id, this URL totally doesn't make sense - and neither should it! Should the image be resized before being executed? How exactly does one change the height of an ASCII string? Maybe you want an image of the ASCII string that has been resized? Ambiguous request! Undefined behavior!

    /image/1/piet?w=640&480 -> 400, bad request.

But these same operations could be done on a video stream. POST creates a new video stream identifier; streaming source opens a websocket/webrtc/whatever based on that identifier; GET /stream/1/hls -> hls chunked stream of the incoming source video; GET /stream/1/dash -> DASH chunked stream of the incoming source video. Uh oh, source stream disconnects due to a network glitch. That's okay, they can just re-open it with the same identifier. Source stream PUT /stream/1 : notifies the server that it is complete, server can cease to accept new streaming inputs for /stream/1; GET /stream/1/hls now returns a 301 redirect to /video/1/hls, which contains the entirety of the video that was streamed, as the server received it.

Or do you have some other domain in mind that doesn't involve flubber?

Hey, I didn't say anything against the Microsoft stack; I've made a living off it myself, at times, although mostly at a lower (i.e. VBA) level. But it doesn't really lend itself to easy understanding of REST.

As far as REST vs. RPC goes, there is a sole essential difference: the semantics of interaction with a REST resource are defined in RFC 2616, and a correctly designed and implemented REST resource behaves in accord with what you find there.

REST itself, meanwhile, being just HTTP, is very simple, and very well suited to expressing interactions with resources and collections of resources. Especially in the front-end/full-stack development world, most things can be expressed, with little or no semantic strain, as resources and collections of resources, and capable HTTP clients are highly available. (And the convention of encoding structured data as JSON in request bodies is very strong, besides.)

Conversely, there are as many RPC-over-HTTP standards as there are implementations; since doing RPC over HTTP necessarily means mapping whatever semantics you have in hand to an interface not designed to express them well, this makes headaches for people who have to develop against them, especially when writing an application that draws together many disparate APIs in order to do something interesting at their conjunction.

Whether REST is better than RPC over HTTP, or vice versa, strikes me as a question for a philosopher. But, in most cases of interacting with a remote resource over an HTTP transport, REST is certainly more natural, that is, closer to the native semantics of the transport, which results in thinner glue layers and more easily understood behavior.