How to design a RESTful collection resource?

问题:

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 

Remove collection:

==> DELETE /service/items  

Removing a single item from the collection:

==> DELETE /service/items/item1 

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)

回答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/.

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.

回答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.

回答3:

What's wrong with PUT to create an element? You cited the HTTP RFC, but the HTTP RFC doesn't preclude the use of PUT to create an element in your collection, as far as I know. If I've missed something, please make a specific citation, with an excerpt.

The key difference between PUT and POST to create elements:
PUT should be an idempotent operation; POST is not.

For deleting multiple elements in a single transaction, you can send DELETE to a URL that specifies a range (/service/items/13-20, or you can send DELETE to /service/items and use the HTTP Range header (See RFC2616 sec. 14.35.2). Normally the range header is contrued to imply a byte range, and is used on a GET request, but it's up to your resource to infer the meaning of RANGE on a DELETE.

回答4:

Why not use the AtomPub spec and adhere to the decisions written there? This way new clients could easily consume your data (using GData libraries..simple) and things like paged data feeds and the symantics of GET/POST/PUT/DELETE are solidly defined. Just my $.02.

回答5:

Use Content-Type /text/uri-list and manage with PUT,GET,PATCH,DELETE a list of links to the resources you want to collect.

The PATCH format you need could be very simple: just prefix with "+ " or "- " the modality of the change each uri bring to the collection. Unfortunately, this media type, which could be named text/uri-list-update, is not yet officially registered, to my knowledge.

文章来源: How to design a RESTful collection resource?