Using Extras for Fine-Tuning API Usage

The Buzz API supports path-based extras as well as the options parameter, each of which modify the behavior of the API. These are optional and can be used to debug or fine-tune your API usage.

Extras

Extras change the behavior of the API in fundamental ways and are mutually exclusive (only one per API request).

Extras are utilized by including the extra name in the path of the request as shown in the cURL example below where the strict extra is included:

curl -X GET "[host]/rest/advertiser/strict" -b cookies.txt 
	-d '{"advertiser_name":"advertiser", "active":1}'

Supported Extras and their behavior are shown below:

extra	executes API call?	Functionality
`fields`	No	Returns a JSON representation of the fields of the object being requested, along with whether the field is required or searchable.
`help`	No	Returns custom help for the object. (Note, this is not widely implemented at this point)
`strict`	Yes	Treats the JSON request strictly, throwing errors if there are extra, non-valid fields within the request and throwing a 409-Conflict error when any WARNINGs are incurred.
`upload`	Yes	Allows for file uploads, when supported by the API object (usually Creative Assets)
`validation`	No	Validates whether the request is valid but does not execute.
`views`	No	Returns an array of available views for the object as well as the fields and metadata for that view. Useful for creating a UI on Buzz.

Options

Every API request to Buzz may include an extra parameter, options that modifies the response from the server. Options may be combined with each other, as well as with Extras.

In the example below we are using both the time and compact options. Options should be passed as a list, though for convenience when passing a single option a string is allowed.

curl -X GET "[host]/rest/advertiser/strict" -b cookies.txt 
	-d '{"advertiser_name":"advertiser", "active":1, "options":["time","compact"]}'

option	result	notes
`time`	Adds an extra field in the response showing the execution time of the request in milliseconds.	Formerly the `time` parameter was an Extra, which is now deprecated.
`pretty`	API response will be padded with whitespace to make it easier for human readability (opposite of `compact`).	Based on your system setup, either `pretty` or `compact` may be your default. You can have this switched as required.
`compact`	API response will have all whitespace removed to reduce filesize (opposite of `pretty`)	Same as above.

Timezones

By default all API requests are returned in the Account-level timezone, generally America/New_York. API users can force all date fields to be in another timezone for convenience by adding the X-Timezone header to the API request with a valid timezone.

#Request all dates in UTC
curl -X GET "https://canary.api.beeswax.com/rest/advertiser" -b cookies.txt 
	-d '{"rows":1}' -H "X-Timezone: UTC"

#Request all dates in Los Angeles
curl -X GET "https://canary.api.beeswax.com/rest/advertiser" -b cookies.txt 
	-d '{"rows":1}' -H "X-Timezone: America/Los_Angeles"