PUT-ting Objects with the API

📘

Migration Notes from 0.5 API

• In Buzz 0.5 the unique ID of the object to be updated could be included in the body of the request or in the path. In the 2.0 API the ID must be in the path.
• The Buzz 2.0 API now supports both PUT and PATCH methods for more flexibility.

Updates use the PUT http method. In order to update an object you must pass the unique key of that object in the path of the request. For example, if you wish to update a user, the id of that user must be passed in the request URL.

Basic PUT Syntax

curl -X PUT "[host]/rest/v2/[resource]/123" -b cookies.txt -d '{"field_name":"new name"}' -H "Content-Type: application/json"

On a successful PUT the API will return the object as updated. In an error case the PUT will return a JSON error response. Examples are given here: POST-ing to Creating Objects.

PUT vs PATCH

The Buzz API supports the PATCH method. PATCH lets you update specific fields in an object without including all other fields in the request. Fields that are not included in a PATCH will not be validated. For example, imagine an object with two fields, required_field and optional_field. The following PUT will fail, since required_field is not present, while the PATCH will succeed:

#This will fail since required_field is not present
curl -X PUT "[host]/rest/v2/[resource]/123" -b cookies.txt -d '{"optional_field":"new name"}' -H "Content-Type: application/json"

#This will work since only the optional_field is validated
curl -X PATCH "[host]/rest/v2/[resource]/123" -b cookies.txt -d '{"optional_field":"new name"}' -H "Content-Type: application/json"

Bulk PATCH

For certain objects, you can update multiple objects in a single PATCH by using the dedicated /bulk resources corresponding to the object you wish to update. For example, to update multiple Roles in a single transaction, you can PATCH to /roles/bulk.

There are two options for the syntax. To make different changes to fields within different objects, you can specify a list of objects to update, with each object containing its unique id field, as shown below:

#Option 1, object syntax, each object treated separately
curl -X PATCH "[host]/rest/v2/[resource]/bulk" -b cookies.txt 
    -d '[{"id":1, "active":true},{"id":2, "active":false}]'

To apply the same field updates to a list of objects, you can specify the IDs for all target objects in the URL path as shown below:

#Option 2, path syntax, the field changes are applied to all objects specified
curl -X PATCH "[host]/rest/v2/[resource]/bulk?ids=1,2" -b cookies.txt 
    -d '{"active":true}'

On a successful bulk PATCH the API will respond with a list of all the objects updated. If any errors are encountered the entire operation will fail and the response will provide feedback.