5

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

Vasiliy Faronov
  • 11,840
  • 2
  • 38
  • 49
Stephen Last
  • 5,491
  • 9
  • 44
  • 85

2 Answers2

6

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

Community
  • 1
  • 1
Vasiliy Faronov
  • 11,840
  • 2
  • 38
  • 49
  • I mostly agree, but `PATCH` is really unfit for resource deletion: if you apply the semantics correctly, you are ending up with *empty* resources (or presentations thereof) instead of *inexsitent* ones. – DaSourcerer May 10 '16 at 13:51
  • @DaSourcerer `/employees/46/groups` is the set of *all* groups (of which employee 46 is a member). We only want to remove *some* of them. So we patch that set with a document that describes which groups to remove. The only problem is that you need to carefully choose the format of that document and assign a correct `Content-Type` to it. [JSON Patch](http://tools.ietf.org/html/rfc6902) may be a good fit here. – Vasiliy Faronov May 10 '16 at 13:59
  • @DaSourcerer I don't agree fully. F.e. [JSON Patch](http://jsonpatch.com/) has a `remove` operation which is intended for removing values from an object or a list. While for a single document this may only affect one entry (per operation) of that document, if you zoom out at least one level you are in a defacto directory resource of the contained resources and thus should be able to remove subresources without any big hurdles. Important to know however, all operations need to be exucted in a transaction (either all or none succeed) – Roman Vottner May 10 '16 at 14:16
  • @RomanVottner @VasiliyFaronov I see your point, but believe me: You are wrongly assessing the semantics of the `PATCH` method as well as the scope of the `remove` operation in JSON Patch. Just re-read slowly what you wrote and compare it to the specs. You will come to the conclusion that you are about to use the wrong tools for the wrong job. – DaSourcerer May 10 '16 at 14:26
  • @DaSourcerer Perhaps you could post a [question+answer](http://stackoverflow.com/help/self-answer) here on SO to explain this? – Vasiliy Faronov May 10 '16 at 14:30
  • @VasiliyFaronov Do you really want me to lay down why you cannot patch a resource out of existence? If so, I'll have to ask for some patience as this is going to take some time that I possibly cannot spare today. – DaSourcerer May 10 '16 at 14:55
  • Think I'm going with `DELETE /employees/46/groups?ids=12,15,32` as you suggest, because it represents the resource being deleted most closely. I definitely won't run into the really large id list issue, [2000 characters](http://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url-in-different-browsers) is more than enough. – Stephen Last May 10 '16 at 15:33
0

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.

Aboozar Rajabi
  • 1,683
  • 21
  • 26