How to design a RESTful collection resource?

Question

I am trying to design a "collection of items" resource. I need to support the following operations:

1. Create the collection
2. Remove the collection
3. Add a single item to the collection
4. Add multiple items to the collection
5. Remove a single item from the collection
6. Remove multiple items from the collection

This is as far as I have gone:

Create collection:

==> POST /service Host: www.myserver.com Content-Type: application/xml <collection name="items">  <item href="item1"/>  <item href="item2"/>  <item href="item3"/> </collection>  <== 201 Created Location: http://myserver.com/service/items Content-Type: application/xml ... 

Remove collection:

==> DELETE /service/items  <== 200 OK 

Removing a single item from the collection:

==> DELETE /service/items/item1 <== 200 OK 

However, I am finding supporting the other operations a bit tricky i.e. what methods can I use to:

• Add single or multiple items to the collection. (PUT doesn't seem to be right here as per HTTP 1.1 RFC
• Remove multiple items from the collection in one transaction. (DELETE doesn't seem to right here either)

Answer 1

You would be better off using a non-positional identifier such as a UUID for collection items, to avoid problems such as the url of an item changing when you delete an item that precedes it. (Of course, you can still use itemN or just N, as long as the number stays attached to the same item at all times, leaving gaps after deletions, but a UUID is less confusing.)

The collection has the url /service/items/. Each item has the url /service/items/<id>.

1. Creating items and collections is a POST on the parent of the resource.
   1. You could use a PUT if the client has the right and ability to generate the name or id of the resource.
2. Removing items and collections is a DELETE on the resource itself.
3. Adding multiple items is either multiple POST or a multi-item POST on the parent (the collection).
4. Removing multiple items is a DELETE on each resource. I would discourage multi-item DELETE for two reasons:
   1. Bulk deletion is a dangerous operation (for which reason, I would also discourage DELETE on a non-empty collection).
   2. The only meaningful target of the operation is the parent collection, thus making bulk DELETE asymmetric with respect to single-item DELETE.

If you really need bulk deletion capability, provide it through a different, clearly marked API, such as PURGE /service/items.

Answer 2

to add items to the collection, you POST them to the collection's URL (http://myserver.com/service/items). in your case, you already have a 'multiple items' representation in XML, just POST that.

I don't know a simple way to remove multiple items on a single operation... may you could PUT to the collection's item with a list of id's to retain. the idea being that PUT updates the container, so what's not there is removed. and, i think it's not useful to provide the whole data you want to keep, just the references of the items.