21

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

product-groups/123/products
  1. If I need to add to the collection, is it OK that I pass only some products with PUT?

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

  • Are the items in the products group separate resources managed elsewhere? Or are they only part of the product group collection? If separate, can products belong to multiple product groups? – Martijn Pieters Mar 22 '13 at 17:36
  • 2
    perhaps PATCH This specification defines the new HTTP/1.1 [RFC2616] method, PATCH, which is used to apply partial modifications to a resource. – Esailija Mar 22 '13 at 18:01
  • A product (ID) can belong to several product groups. – user151851 Mar 22 '13 at 18:02
  • Is there a well known way (best practice) to say how to PATCH i.e. add or delete products in the collection? – user151851 Mar 22 '13 at 18:32
  • Similar question on SO stackoverflow.com/questions/411462/… – Luke Puplett Jan 5 '16 at 12:39
10

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.

  • 2
    PUT is a replace operation. Calling PUT on a collection endpoint with "some products" should delete (in the OP's case, delete the relationship to) any product that is not included in the list of "some products". While it could be used to add items, it should also remove items which is not (in my opinion) what the OP expects. You should revise your response to their first question accordingly. – claytond Mar 22 '18 at 20:18
  • @claytond: I suppose the answer is fine, as long as a partial update is done with PATCH, and a complete replacement, via PUT. – 9000 Mar 22 '18 at 21:01
  • 4
    @9000. Of course, but the answer currently says "you are encouraged to... add to the collection... [by] pass[ing] only some products with PUT". That's certainly incorrect. Encouraged to POST. Able to PUT... but only by passing all (not some) items. – claytond Mar 22 '18 at 21:30
5

Usually, REST methods are intented 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 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 limitatio of GET and DELETE to have an empty body)

  • Sure, there are a few methods to do reach the goal. Which one is the best practice? Which one will be more future-proof? – user151851 Mar 22 '13 at 18:30
  • 4
    @user151851: Total REST compliance (if there is such a thing) is a lofty goal. The approach outline here seems more realistic, inasmuch as it attempts to employ an approach that is actually being used in the "real world," making it, in essence, a defacto-standard. That's about as future-proof as you're going to get. – Robert Harvey Mar 22 '13 at 18:49
  • 2
    Don't we introduce custom verbs using "append" and "delete" in the URL? In that way we will have to explain how use the API. Shouldn't we reuse what we have i.e. the HTTP methods? In which case the actions are well-known. – user151851 Mar 22 '13 at 19:34
  • 7
    For anyone else who happens into this answer: It's wrong. As @user151851 mentioned, this introduces verbs into the URL which is about as non-RESTful as you can get. In regards to the actual question, I don't have a great answer, but this one's not it. – umbrae May 14 '14 at 22:37
  • Could the "extension" be more resource-oriented by making it products/collection which returns an 'envelope' of items and the envelope contents changed via a PUT? Like, "here's exactly how I want the items in the collection to be". – Luke Puplett Jan 5 '16 at 12:37
3

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://www.factory.net/products/

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

https://www.factory.net/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.

2

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.

Not the answer you're looking for? Browse other questions tagged or ask your own question.