Is it OK to partially change a collection with PUT or DELETE?

I have a collection of products in a product group e.g.:

product-groups/123/products

If I need to add to the collection, is it OK that I pass only some products with PUT?
If I need to delete some products from the collection, is it OK that I pass filter data (an array of ID’s) with DELETE?

What’s the best way to implement the functionality in the spirit of ReST?

Edit: the items are links to separate entities, basically ID’s of products.

In general you have one endpoint which represents the whole collection of x:

/products

Say, you want to update a single product, you make a PUT to /products/{id}.
If you want to partially update a single product (not updating every field), you could also use a PATCH to /products/{id}. The same goes for deletion of a single entity (DELETE to /products/{id}).

If you want to target a single ressource, you qualify via path, which single ressource, you want to modify.

The only action which breaks the scheme is the creation of a ressource. When creating a ressource you target the collection as a whole, say POST to /products.

That said, it should be clear, that the target for operations affecting the collection as a whole, should go to the appropriate collection-endpoint.

E.g. you want to retrieve a subset of products which are red, you ask for it by

GET to /products?colour=red.

So, if you want to delete all of these, you DELETE /products?colour=red. Or if you want to delete some of the products via id, you could DELETE /products?id=1&id=2&id=3.

What about bulk creation of ressources? POST your collection [{...},{...},{...}] simply to /products. The same goes for PUT and PATCH.

That’s really straightforward.

To answer your questions:

If I need to add to the collection, is it OK that I pass only some products with PUT?

It is not only OK, you are encouraged to do it like that.

If I need to delete some products from the collection, is it OK that I pass filter data (an array of ID’s) with DELETE?

That is okay. As Eneko Alonso wrote, sometimes there are bulkoperations encapsulated via “controller”-endpoints, i.e. a POST is used to trigger (complex) operations.

Usually, REST methods are intended to operate on a single entity/object (CRUD).

There are several options:

Treat your collections as entities and update them via POST
Create alternate, non-REST operations

The first one follows REST standards, but can be costly, since your collection objects/entities may be very large (updating a group that has thousands of products just to add/remove one product would be a heavy request).

The second option is preferred by many APIs, as a way to extend REST beyond the CRUD operations.

For example:

GET product-groups/123/products (list all the products in the group)
POST product-groups/123/products/append (POST a list of new product ids to append to the group)
POST product-groups/123/products/remove (POST a list of product ids to remove from the group)

Many APIs use always POST for this extended operations, but nothing limits you to use other http methods (other than the limitation of GET and DELETE that needs to have an empty body)

In principle, all of the RESTful operations are valid on a collection, but make sure you understand how the semantics of the verbs apply to a collection:

PUT is a complete replacement.
- If you PUT to a singleton (e.g. /item/{id}) and leave name out, it should be cleared or set to null or something similar.
- If you PUT to a collection and do not include an item, it should be removed from that collection.
While a PUT can be used to add items, you must send “all” items. Sending “some” items should result in removals (I assume this is not what the OP desires).
DELETE is more intuitive. It is valid to delete the collection or any filtered subset thereof. Only the items included in the filter should be affected.
PATCH is also valid. In theory, you’re supposed to provide a list of “operations”. For example, you should technically send something like:
```
[{ 
    "action": "update",
    "id": <id>,
    "value": {...}
},{
    "action": "add",
    "value": {...}
}, ...]
```
In practice, it’s more common to see an API that accepts a partial list of objects where each item is processed using an UPSERT (update or insert) logic.
Technically, POST should process the input “according to the resource’s own specific semantics”.
- In practice, POST is normally used for “create” operations.
- However, POST is also the verb used for non-standard calls. While there’s vigorous debate whether action endpoints are strictly RESTful (I side with the “no”s), POST is the appropriate verb if you were submitting a request to an endpoint like {resource}/activate.

NOTE: When using non-GET operations on collections, carefully consider the definition of success and failure. REST does not give you a good way to communicate partial success. A good default is to assume that you will run the operation in a transaction with an all-or-nothing success criteria. If this is not what you want, you probably should not be interacting with the collection directly.

Just to precise previous answers / comments.

As per my knowledge, POST is the method to add single elements to the collection.

DELETE in turn, is the method to delete single element from the collection. Both scenarios are perfectly RESTful.

However, you should use appropriate URI to refer single element or the whole collection.

For example, to add element to collection you should POST data to following URI:

https://example.com/products/

To delete single product from the collection, you could use DELETE method sending request to something like:

https://example.com/products/108/

The PATCH method can be used to update some elements within the collection. For instance, when you only need to update one field in one element. PUTting a complete resource representation for very large collection can be very costly operation.

Filed under: softwareengineering - @ 14:50

Thẻ: collections, rest

Thiết kế website giá rẻ

Danh mục

Is it OK to partially change a collection with PUT or DELETE?