RESTful API - DELETE some of a resource collection?

Question

I can DELETE a single resource like:

// Removes group 12 from employee 46
DELETE /employees/46/groups/12

I can DELETE a whole resource collection like:

// Removes all groups from employee 46
DELETE /employees/46/groups

I'm looking for the proper RESTful way to DELETE some of a resource collection.

1. DELETE /employees/46/groups { ids: [12, 15, 32] }
2. DELETE /employees/46/groups?ids=12,15,32
3. DELETE /employees/46/groups/xx (single, but call it 3 times)

Should query string parameters ( ?ids=12,15,32 ) only be used with GET ..?

Should the request body ( { ids: [12, 15, 32] } ) always be used with POST , PUT and DELETE ..?

All three of these will work, but which one is the standard way to DELETE only some of a resource collection..?

Answer 1

JSON API uses approach number 1 ( DELETE /employees/46/groups with a body). I think that's fishy, because RFC 7231 § 4.3.5 basically says that the entire target resource ( /employees/46/groups ) is to be deleted, regardless of what's sent in the body. However, others disagree .

I think DELETE /employees/46/groups?ids=12,15,32 is best, because it considers the set of groups you want to delete as a resource of its own. You can give links to in your hypermedia. You can later support GET on it (but you don't have to).

No, there is absolutely nothing preventing you from sending non-GET requests with a query string. The query string is not some kind of “parameter” (although it's often useful to treat it like that), it's an integral part of the resource's URI. In fact, you could use DELETE /api.php?type=employee&id=46&groups=12,15,32 and that would still be perfectly RESTful. The whole point of REST is that URIs (among other things) should be opaque to the client.

However, the query string approach may pose problems when you want to delete a really large number of groups in one request. If that happens, the simplest approach is a POST /bulk-delete-groups RPC call. You may also consider PATCH /employees/46/groups (but please read RFC 5789 errata first).

Answer 2

Most APIs don't allow to delete a collection of resources at a time but it's possible to perform other operations on entities like:

DELETE /employees?id=12,15,32

or

DELETE /employees?id=12&id=15&id=32

A good choice maybe the non-REST way, to send a custom JSON object containing the ID's marked for deletion.