For REST, we know we should use URL as endpoint and it should be consistent. It's also presented to us an structure for entities. But let's dive a little on it, ok?

First of all, HTTP standards evolve. Today, there is a lot of HTTP standards. We will concentrate our efforts on the standards that define the HTTP Methods.

The common methods are:

• GET
• POST
• PUT
• PATCH
• DELETE

The methods GET, POST, PUT, and DELETE are defined in RFC 9110 (HTTP Semantics). The PATCH method is defined on RFC 5789 (Patch Method for HTTP).

Now, we see the definitions of the HTTP Methods.

GET

"The GET method requests transfer of a current selected representation for the target resource. [...] retrieving identifiable information via HTTP is usually performed by making a GET request on an identifier associated with the potential for providing that information in a 200 (OK) response." RFC 9110 section 9.3.1

So, the GET method is indeed a standard or default method to retrieve information.

POST

"The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics. For example, POST is used for the following functions (among others):

• Providing a block of data, such as the fields entered into an HTML form, to a data-handling process;
• Posting a message to a bulletin board, newsgroup, mailing list, blog, or similar group of articles;
• Creating a new resource that has yet to be identified by the origin server; and
• Appending data to a resource's existing representation(s)." RFC 9110 section 9.3.3

POST looks like a general function handling method. If we want to pass data to be handled by some application function, we use POST.

It's surprising that one of the purposes is to create an entity in a list. If guessing, I would say that it would be the intention of the PUT method.

PUT

"The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message content." RFC 9110 section 9.3.4

If we are looking for a method that is primarily used to create entities, it's PUT! But ONLY if you have the correct address. If we must add an entity with no pre-defined URL, we must use POST.

There is one problem. HTTP recognizes endpoints as entities. For example, this is the location of user with id = 1000:

/users/1000

But it's common when we add an entity it have not an id. It's created on demand at database. So, at creation, we must visit something like this:

/users

We can't use PUT there because we are not creating an entity on /users. So, we should use POST. It seems not right for me because of the general nature of POST. So, we use PUT to creation, but only in a specific situation. The other 99% of the time we use the general Method POST.

PUT also should be used to update an entity. It allows the application to change (or replace) the entity in the current URL.

DELETE

"The DELETE method requests that the origin server remove the association between the target resource and its current functionality." RFC 9110 section 9.3.5

It's simple and direct. Although we don't have a method to delete many resources at once, relying again on POST.

PATCH

"The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request-URI. The set of changes is represented in a format called a 'patch document' identified by a media type. If the Request-URI does not point to an existing resource, the server MAY create a new resource, depending on the patch document type (whether it can logically modify a null resource) and permissions, etc." RFC 5789

If we need to change a piece of the resource, we can decide to send only the changed field to the entity specified. It's just a patch.

The definition also allows the application to create an non-existing entity at that location.

Meaning PATCH purpose overlaps with PUT.

Conclusion

There is no direct connection between our application entities and HTTP entities. REST try to solve this issue with standard paths (URL) to our entities, but it's not a good match.

That's why we try to use the correct methods (and returns) to handle the REST-based application. But I personally think that we should rethink the role of POST in this play.

For me it seems more natural to use:

• GET: for general fetch
• POST: for general function, not covered by other methods
• PUT: on /collection to create
• PATCH: for changing some fields
• DELETE: on /collection for multiple deletion