"docs.beeswax.com" has a new address: "api-docs.freewheel.tv/beeswax." Please update your bookmarks accordingly.

DELETE-ing Objects with the API

Deletes use the http DELETE verb. In order to delete an object you must pass the unique key of that object. For example, if you wish to delete a user, the user_id field must be present in the JSON request (other fields are ignored). Note, that most object have extensive validation to prevent data inconsistencies and it may not always be possible to delete an object. Generally, to delete something in Buzz you need to be assured that no other object is dependent on the object to be deleted. For example, Buzz will not allow you to delete an Advertiser, if a Campaign belongs to that Advertiser.

Example DELETEs

Some examples of successful and unsuccessful DELETE requests:

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

UNSUCCESSFUL: advertiser_id must be provided

curl -X DELETE "[host]/rest/advertiser" -b cookies.txt -d '{"advertiser_id":1}'

SUCCESSFUL: advertiser_id 1 is deleted

curl -X DELETE "[host]/rest/advertiser" -b cookies.txt -d '{"advertiser_id":[1,2]}'

SUCCESSFUL: advertiser_id 1 and 2 are deleted

Example DELETE Requests

In order to delete 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 DELETE "[host]/rest/user/1" -b cookies.txt

Which is equivalent to:

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

Using the ID in the path may be desirable since the http specification does not support a data payload on DELETE and some IDEs may not allow it.

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

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

Multiple Object Deletes

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

Successful UpdatesHTTP statusMessage
All200Success message
Partial200WARNING message. The "payload" object will provide details on why some deletes failed.
None406 or other error code as appropriateERROR message. The "payload" object will provide details on why deletes failed.

When using "Strict mode" the API will treat any errors as fatal and will not delete any objects. This may be useful if your application wishes to avoid partial deletes.