A command as the intended effect of POST versus as the side effect of PUT

Question

The intended effect (semantics) of the POST method is resource specific, e.g. executing a command with arguments:

POST /command HTTP/1.1

{"parameter-1": "argument-1", "parameter-2": "argument-2"}

The intended effect (semantics) of the PUT method is to create or replace the state of the target resource with the state defined by the enclosed representation, but the side effect of the PUT method is resource specific, e.g. executing a command with arguments:

PUT /command HTTP/1.1

{"parameter-1": "argument-1", "parameter-2": "argument-2"}

Cf. RFC 7231, § 4.3.4:

A PUT request applied to the target resource can have side effects on other resources. For example, an article might have a URI for identifying "the current version" (a resource) that is separate from the URIs identifying each particular version (different resources that at one point shared the same state as the current version resource). A successful PUT request on "the current version" URI might therefore create a new version resource in addition to changing the state of the target resource, and might also cause links to be added between the related resources.

So what are the benefits of executing a command as the intended effect of POST versus as the side effect of PUT?

Answer 1

As you state in the question the difference is intent. A side effect of a PUT should not matter to the caller and they are not responsible for it. The intended effect of a POST is what the caller is doing and is their responsibility. If you control both the client and server, you are pretty free to do what you like but I don't see any good reason to break convention.

However, if your intended effect (not side-effect) is idempotent, PUT can be used (RFC7231 section 4.2.2)

A request method is considered "idempotent" if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request.

Answer 2

If I PUT a resource representation, then the expectation is that a GET of the same resource returns an equivalent representation. For example, if I PUT /command with body print("hello world"), when a later GET /command might get back the command, or the result of executing the command.

A successful PUT of a given representation would suggest that a subsequent GET on that same target resource will result in an equivalent representation being sent in a 200 (OK) response.

(RFC 7231)

With a POST, there is no expectation of the resource at that URL being created or updated. It is quite common that a POST to an URL creates a different resource (to which a 303 See Other or 201 Created response might redirect). But a POST might not touch upon any resources, and be invoked purely for its side effects.

For example, let's consider a HTTP-based version control system. Each version is identified by an URL like /version/d1623a5. There are also floating labels like /version/latest. How would different designs create a new version?

• In a PUT-based design, I might directly create a version resource by PUTting a new representation to its URL:

  > PUT /version/c0af447
  >
  > the new content
  
  < 201 Created
  

  As a side effect, this might update the resource that /version/latest points to. Such a PUT is also idempotent. If it fails, I can safely retry it. If the version resource already exists, I would probably get a 204 No Content response.

  Alternatively, I might PUT the latest version:

  > PUT /version/latest
  >
  > the new content
  
  < 204 No Content
  

  As a side effect, this might create the resource /version/c0af447.

• In a POST-based design, I would not directly POST to the version resources, but to a URL that creates new versions:

  > POST /version/new
  >
  > the new content
  
  < 303 See Other
  < Location: /version/c0af447
  

  This cannot be retried safely: a repeated POST request would typically create another version.

  In practice, using POST is still very popular because it is quite general-purpose, and is less constrained than a PUT. It is a reasonable default for changing “something” on the server.