Migrating from Line Item 0.5 to 2.0

Beeswax currently offers two versions of the REST API, the legacy 0.5 version and the newly-released 2.0 version. It is our intention to upgrade all 0.5 endpoints to 2.0 and to migrate customers to the new version gradually.

“Why API v2 is good for you”

We have made key changes to the line item v2 API to provide users with a easier and clearer set up when creating and maintaining the line item object. These benefits include:

• For better readability, the API has been consolidated into a primary endpoint to provide all key details in one main field
• Support for descriptive strings has been added to users can easily read the values in the JSON request
• Structural changes to the API fields will allow for better readability when creating and editing your Line Item object
• Stricter logic has been added to provide a cleaner JSON request. With this logic, the payload will remove irrelevant fields when certain fields are not defined which simplies the payload
• Backward compatibility with v1
• Improved API support for bug fixes and new feature enhancements

As of today, line item v2 endpoints are available in the 2.0 API.

Important note: all values in the v2 API response are CASE SENSITIVE

Compatibility

The 2.0 API is backwards compatible with the 0.5 API but we encourage the usage of V2 endpoints be used with the V2 UI.

Update Paths

The 0.5 API uses the path /rest/[resource] while the 2.0 API uses the path /rest/v2/[resource]

Authentication

While we are transitioning from the Buzz 0.5 API to the new Buzz 2.0 API you must authenticate using the 0.5 authentication. Once you have authenticated, you may make calls to either the 0.5 API or the 2.0 API using the same cookie.

Object Hierarchy

The basic hierarchy of objects in the Buzz system is not changing with the release of the Buzz 2.0 API. The documentation describing these objects may be found in the 0.5 documentation hub.

Key Structual Changes and Comparisons:

Change #1: Descriptive Strings

We use things like descriptive strings for some of the fields that will be listed in the API schema, rather than primary key references to static data

For the following endpoint GET rest/v2/line-items/{id}, the value that is accepted will change to a “type” and support the enum of either banner, video, or native values.

V1

{
	"line_item_type_id": 0,
}

{ 
    "type": "banner", 
} 

Change #2: Nested Structures

In the V2 API response, we implemented a nested object structure for better readability.

These changes are applicable to GET, POST, PATCH and PUT

For example:

• In the representation of the bidding field, the names were changed
• The bid_shading and bid_shading_win_rate_control fields were merged into one: bid_shading_control.
  • This field will take the same values as bid_shading_win_rate_control
• When specifying it in the payload, we automatically determine that the bid_shading field is enabled (this logic happens on the backend side).

{ 
    "bidding": { 
        "bidding_strategy": "CPM", 
        "custom": false, 
        "pacing": "none", 
        "values": { 
            "cpm_bid": 10 
        }, 
        "bid_shading": 0, 
        "bid_shading_win_rate_control": "NORMAL" 
    }, 
} 

{ 
    "bidding": { 
        "strategy": "CPM", 
        "values": { 
            "cpm_bid": 10 
        }, 
        "pacing": "none", 
        "custom": false, 
        "bid_shading_control": "normal" 
    }, 
} 

Additional changes...

• For better readability, we changed the structure of the v1 API to allow for nested fields, consolidated values and route elements to help clean up the JSON request. This will help provide a clearer payload when specifying certain fields.
• V2 includes consolidated values, particularly apparent in the representation of budget in line item v2. Budget amounts are split into independent fields such as: impression amount or spend amounts. Either field will be nullable depending on the budget type set for the line item
• Route elements: For ease of use and simplicity, we’ve added functionality to our nested structures to support route elements. For example line item creative association are exposed under the rest/v2/line-items/{id}/creatives endpoint which supports a list, bulk set, and the ability to add, update and delete an association.

Errors

To provide users with a more thorough overview of line item issues, we have introduced a new validate endpoint to respond with errors and warnings. This change provides a more structured view of line item issues.

"errors": { 

    "advertiser_id": [ 
        "This field is required." 
    ] 
}, 
"warnings": { 
    "impressions_budget": [ 
        "This campaign is budgeted using spend." 
    ]

Review Full list of Changes

See our complete list of all API changes for line item v2. Here you can review an outline of all expected changes impacting our line item API. Line Item V2 API Changes