Beeswax

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"

Updated 7 months ago

Using Extras for Fine-Tuning API Usage


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.