What HTTP method should I use for an endpoint that updates a status field of multiple entities

Question

I like to use the correct HTTP methods when I'm creating an API. And usually it's very straightforward. POST for creating entities, PUT for updating them, GET for retrieving etc.

But I have a use-case here where I will create an endpoint that updates the status of multiple objects given 1 identifier. e.g.:

/api/v1/entity/update-status

But note that I mentioned multiple objects. The initial thought of my team would be to use map it as POST, but it won't actually be creating anything, plus if you were to call the same endpoint multiple times with the same identifier, nothing would change after the first time. Making it idempotent.

With this in mind, my idea was to create it as a PUT or even PATCH endpoint.

What do you smart people think?

Answer 1

I imagine PATCH would be the most correct way. Although if you use a PUT it would also not be incorrect.

The difference between the PUT and PATCH requests is reflected in the way the server processes the enclosed entity to modify the resource identified by the Request-URI. In a PUT request, the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version. The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH.

Answer 2

Whilst it is a convention in REST APIs that POST is used to create a resource it doesn't necessarily have to be constrained to this purpose.

Referring back to the definition of POST in RFC 7231:

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).

Clearly creation is only one of those purposes and updating existing resources is also legitimate.

The PUT operation is not appropriate for your intended operation because again, per RFC, a PUT is supposed to replace the content of the target resource (URL). The same also applies to PATCH but, since it is intended for partial updates of the target resource you can target it to the URL of the collection.

So I think your viable options are:

POST /api/v1/entity/update-status

PATCH /api/v1/entity

Personally, I would choose to go with the PATCH as I find it semantically more pleasing but the POST is not wrong. Using PATCH doesn't gain you anything in terms of communicating an idempotency guarantee to a consumer. Per RFC 5789: "PATCH is neither safe nor idempotent" which is the same as POST.