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.
GET /issues/open HTTP/1.1
Host: example.org
=>
HTTP/1.1 200 OK
Content-Type: application/vnd.collection+json
...
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.
POST /issues/pendingreview HTTP/1.1
Host: example.org
Content-Type: application/vnd.issue+json
Content-Length: ...
{
"id" : 745,
"short-description" : "There is a typo on the home page",
"status" : "Open"
}
=>
HTTP/1.1 200 OK
Content-Location: http://example.org/issue/745
Content-Type: application/vnd.issue+json
Content-Length: ...
{
"id" : 745,
"short-description" : "There is a typo on the home page",
"status" : "Pending Review"
}
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 tbe 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.
Related Patterns
Miniput, Whack-a-mole