What is the purpose of RESTful URIs for POST/PUT/PATCH/DELETE methods?

Question

In the process of conceiving a web application framework, I spent some time pondering the notion of RESTful paths. If I wanted to create e.g. a new topic, I might send a POST request to /topics. The parameters thereof might be something like: { topic: { body: 'Body' } }

As such, the type of resource being created can be inferred from the parameters. Since there is the top-level item 'topic', we can logically ascertain that the request is to create a topic.

For me, the strange thing is that POST create is the one action that falls outside of the notion of either a singular resource or a collection. It is arguably neither. Sure, you're adding to a collection, but in contrast to say a GET index you are not retrieving any part of that collection, and the state of that collection to a large extent is irrelevant. In contrast to a GET, PUT/PATCH, or a DELETE, you are not retrieving a singular item based on an identifier. You are creating an item where one does not exist.

I conceived of a "master registrar" service that would respond to all incoming POSTrequests. Imagine every form POSTing to /, with the master registrar determining the intended resource based on the params, and deferring to services that exist for the purpose of persisting a resource based on those params.

In fact, for any non-GET action, the paths become irrelevant. They don't seem to have an important semantic purpose. A user is not going to link to a form's action URL. Even in the case of PUT, PATCH, or DELETE The type of resource being created or the resource being modified can be inferred from the parameters. For example, if we were editing a topic versus creating one, the parameters might be { topic: { id: 1, body: 'New Body'} }. The presence of an ID in the parameters indicates that the topic in question already exists and should be retrieved foremost.

I don't know if this is RESTful or not. Regardless, I cannot see why this approach is invalid or inadvisable. Given my caution and naivete, however, I'd like to know why it might be.

Answer 1

In most REST APIs, the type of object is not embedded in the payload. That is the job of the resource resolver. Your "master registrar" is equivalent to the typical path resolver found in web servers, except for using embedded types instead of paths.

So instead of your format:

POST    /
{
    topic:
    {
        property1: "value1",
        property2: "value2",
        ...
    }
}

use this one:

POST    /topics
{
    property1: "value1",
    property2: "value2",
    ...
}

This will keep your design DRY while also leveraging standard built-in code as much as possible.

As far as the spec goes, POST is the "everything else" method, used for any processing which does not fit the semantics of GET, PUT, PATCH and DELETE. So you would not be violating the letter of the spec, but you may still end up confusing potential clients of your services because of the non-standard API.

Answer 2

The HTTP spec's definition of POST is very broad. There are two clauses that make it good to treat as the "create" verb.

• It is the method for "append" to a database

• It is the method for general "data processing"

So for REST, the sense of POST is that it's for appending to a collection of resources.

In your example, POST to "/topics" is perfectly valid -- because you're really creating a single item, but extending the collection of all items. Really the target is the collection. There's some data processing along the way.

POSTing to "/" and inferring the type may actually be OK according to the HTTP spec. In a sense, you'd be creating an item and appending it to the collection of all items (!). But IMHO it makes more sense to limit the action to the right resource & just post to /topic.

It's hard to pin down what you're not supposed to do with POST ... remember that the World Wide Web was built with GET and POST. There are cases where it's better to get with a POST than with a GET, if the query is long or uses structured data. Basically, if you want to sail a battleship through a loophole in REST, use post.

(Or, as Roy Fielding has posted, POST is the verb to use when you don't want to generalize the operation.)

Just be careful about confusing your clients. POST to "/topics" instead of "/" might make more sense.