A resource used to indicate the status of a "child" resource.
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.
The bucket resource generally returns a list of entities when a GET method is issued.
A POST request is used to send a representation of the class of resource that is held in the
bucketresource. The process of adding this resource to the
bucketshould change the status of the resource to be the same as all of the other resources held in the
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
200status code should be sufficent to guarantee that the resource status has been updated.
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.
Thanks to Jeff Gonzalez feedback relating to the use of PUT vs POST.