Upcoming Changes to the Buzz API

One of the key elements of the Beeswax solution is our REST API, Buzz. Many Beeswax customers use these APIs as a replacement, or supplement to our user interface (also called Buzz!).

Starting in Summer, 2020 Beeswax has been releasing new resources under a "2.0" REST API. The new API is not backwards compatible with the current version (which has been informally numbered 0.5). This document is meant to help API developers understand the changes, so as to avoid potential missteps in implementation that would need to be re-architected later.

Roll-Out Plan

📘

Buzz API 2.0 Now Available

• The first major functionalities, Targeting, and Reporting, are now available on the 2.0 API
• Read the 2.0 guides to get started.

We started rolling out Buzz 2.0 API endpoints in the Summer of 2020, and will probably finish by Summer 2021. We started with the two most commonly used areas of the API, reporting and targeting (see below for details).

The version 0.5 and version 2.0 APIs will both be supported during this time and developers will be able to stay on the existing APIs for some time. Since we are rolling out resources gradually we expect many developers to use only a subset of 2.0 APIs in conjunction with the majority of functionality in the older API.

For example, an API customer may wish to upgrade to the 2.0 reporting endpoints but remain on all other endpoints until all of those are available.

Compatibility Between 0.5 and 2.0 APIs

As we've been developing the Buzz API over the past four years we have taken pains to avoid changes that were strictly not backwards compatible. For example, deprecated fields were retained in objects in order to avoid breaking any implementations that expected those fields to be present.

With the 2.0 API upgrade we are taking the opportunity to clean up and improve our APIs. In most cases these changes will be minor, but in some cases we will be making major improvements such that the old- and new- APIs are largely distinct.

We will also be modernizing some of the syntax and behavior of the API. To give one example, the current Buzz API does not provide field-level error messages, making it difficult to show an end-user which field caused validation problems, the 2.0 API organizes feedback at the field level.

Documentation

As the 2.0 versions of the API are released, all changes will be thoroughly documented. The 2.0 docs can be accessed by changing the version number on the upper-left side of this page or by going to https://docs.beeswax.com/v2.0/docs/. The site also has a new "changelog" feature, making it easy for developers to keep up with changes to the API.

2.0 Highlight: Reporting

By far the most commonly-used API endpoint in 0.5 API is the Report Queue. We have made a major upgrade to our reporting system called Report Builder and replaced this endpoint entirely with new and more flexible version resources described here. The new reporting API has a number of highly requested features, notably a relaxation of the strict row limits that make API users paginate multiple requests.

2.0 Highlight: Targeting

Generating targeting expressions can be the most complex part of any DSP. In the Buzz 0.5 API targeting expressions are created using a somewhat inflexible JSON object, which has limited our ability to offer more flexible targeting (AND/OR combinations) and prevented more advanced editing capabilities such as bulk-edit.

We have launched an entirely new targeting API, which we strongly recommend to all customers. The transition to the new targeting requires a one-time customer-level migration, and therefore, the new capabilities cannot be enabled for a customer if API users require compatibility with the 0.5 endpoints. So while the 0.5 endpoints will continue to be supported, we recommend all API users to move to the 2.0 functionality.