Image alternative text

Name: Bucket

A resource used to indicate the status of a "child" resource.

Problem

A user wishes to manage a set of resource that over their lifetime will transition through a set of statuses. The user wishes to be able to change the status of a resource and identify resources that have a particular status, whilst ensuring that no resources exist in two states at once.

Solution

The bucket resource generally returns a list of entities when a GET method is issued.

x
1
GET /issues/open HTTP/1.1
2
Host: example.org
3
4
=>
5
6
HTTP/1.1 200 OK
7
Content-Type: application/vnd.collection+json
8
...
A POST request is used to send a representation of the class of resource that is held in the bucket resource.  The process of adding this resource to the bucket should change the status of the resource to be the same as all of the other resources held in the bucket.
1
23
1
POST /issues/pendingreview HTTP/1.1
2
Host: example.org
3
Content-Type: application/vnd.issue+json
4
Content-Length: ...
5
6
{
7
 "id" : 745,
8
 "short-description" : "There is a typo on the home page",
9
 "status" : "Open"
10
}
11
12
=>
13
14
HTTP/1.1 200 OK
15
Content-Location: http://example.org/issue/745
16
Content-Type: application/vnd.issue+json
17
Content-Length: ...
18
19
{
20
 "id" : 745,
21
 "short-description" : "There is a typo on the home page",
22
 "status" : "Pending Review"
23
}
24
In this example, we returned an updated representation of the resource in the response to the POST.  However, this is completely optional.  There is no need to return a response body and it is not even required to include the status property in the response.  The 200 status code should be sufficent to guarantee that the resource status has been updated.

Discussion

It is recommended that in order to change the status of a resource, a complete representation of the resource is posted. This approach most accurately reflects the client's intent. It is also possible to POST a URL into the bucket, to avoid having to retreive the resource with the old status and then resend that same information to the new bucket. The risk in only sending a URL is that the resource may have changed since the client last retreived it. This could lead to a client doing something that it did not intend to do.

If the risks of sending just a URL are tolerable then there is an additional advantage. By using the 'text/uri-list' media type then you can send multiple URLs and have the ability to change the status of many resources in a single request.

It is possible to use PUT instead of POST to move the resource to a new bucket, however this does require transfering the complete representation. It also introduces a new potential problem in that you now have multiple URLs for what is conceptually the same resource. For example for the resource http://example.org/issue/745 that is pending review, you would also have http://example.org/issue/pendingreview745. This can cause duplicate representations to be stored in a HTTP cache. Duplicate representations cause the cache to be filled quicker and make it much harder to do cache invalidation. The advantage of using PUT would be that the request is idempotent. However, it is fairly easy to make POSTing to a bucket idempotent. If you POST a representation to a bucket that it is already in, then no action needs to be taken.

Related Patterns

Miniput, Whack-a-mole

Acknowledgments

Thanks to Jeff Gonzalez feedback relating to the use of PUT vs POST.