PUT-ting Objects with the API

Updates use the PUT http method. In order to update an object you must pass the unique key of that object. For example, if you wish to update a user, the user_id field must be present in the JSON request along with whatever fields are meant to be updated.

The Buzz PUT method does not overwrite fields that are not present in the request, only those that are explicitly included. In some REST API implementations this behavior is handled by the PATCH verb, but this is not currently supported in Buzz.

Some examples of both successful and unsuccessful PUT requests:

Example PUTs

Some examples of successful and unsuccessful PUT requests:

curl -X PUT "[host]/rest/advertiser" -b cookies.txt -d '{"advertiser_name":"new name"}'

UNSUCCESSFUL: advertiser_id must be provided

curl -X PUT "[host]/rest/advertiser" -b cookies.txt -d '{"advertiser_id":1, "advertiser_name":"new name"}'

SUCCESSFUL: advertiser_id 1 is updated with a new name

curl -X PUT "[host]/rest/advertiser" -b cookies.txt -d '{"advertiser_id":[1,2,3], "default_click_url":"http://www.foo.com"}'

SUCCESSFUL: Advertisers 1, 2 and 3 are updated

Example PUT Requests

In order to update an object you must use the object's unique ID. You can include this ID in the request path as shorthand, as shown in this example:

curl -X PUT "[host]/rest/user/1" -b cookies.txt -d '{"email":"[email protected]"}'

Which is equivalent to:

curl -X PUT "[host]/rest/user" -b cookies.txt -d '{"user_id":1, "email":"[email protected]"}'

When updating multiple objects, pass the IDs as a list:

curl -X PUT "[host]/rest/user" -b cookies.txt -d '{"user_id":[1,2,3], "email":"[email protected]"}'

Multiple Object Updates

When updating multiple objects the http status and messaging will vary depending on whether all, none, or some of the objects were successfully updated as shown below:

When using "Strict mode" the API will treat any errors as fatal and will not update any objects. This may be useful if your application wishes to avoid partial updates. Read more in Using Extras for Fine-Tuning API Usage.