Guides
Beeswax HomeGuidesAPI ReferenceChangelog

Buzz API Versioning Policy

Last Updated: May 19, 2025

This document outlines the API versioning policy for the FreeWheel Buzz API. Our goal is to provide a transparent and predictable framework for API evolution, enabling you to leverage new features and improvements while maintaining stability for your existing integrations.

Our Philosophy on API Evolution

The ad-tech landscape is dynamic, and the Buzz API must evolve to incorporate new functionalities, enhance performance, and adapt to market changes. We are committed to managing these changes in a way that provides clarity and predictability for our developers. This policy is designed to balance the need for innovation with the imperative for stable and reliable API services.

How We Version the Buzz API

Version Naming

The Buzz API uses Major Versions to signify substantial updates, particularly those that include backward-incompatible changes.

Major Versions (e.g., v2.0): Indicate significant changes, including new features, architectural improvements, and potentially backward-incompatible modifications. The transition from our legacy v0.5 API to v2.0 is an example of a major version release.

Minor and Patch Versions: While our most significant historical changes have been through major versions, FreeWheel may introduce minor or patch versions in the future to release backward-compatible features or fixes. Any such changes will be clearly communicated.

Specifying API Version in Requests

Clients must specify the API version they intend to use. For Buzz API v2.0 and subsequent major versions, the version is specified directly in the URL path.

  • Example: https://api.beeswax.com/rest/v2/[resource_name]

Requests to unversioned or unsupported paths may result in errors or be routed to a default supported version, though explicit versioning is always recommended.

Understanding API Changes

We categorize API changes as follows:

Backward-Incompatible (Breaking) Changes

These are changes that may require you to modify your existing client integrations to ensure continued functionality. Examples of breaking changes include but are not limited to:

  • Removing or renaming an existing API endpoint, resource, field, or parameter
  • Changing the data type of an existing field
  • Adding a new required field to an existing request payload
  • Altering the fundamental structure or behavior of a request or response
  • Changing authentication or authorization mechanisms in a way that breaks existing clients
  • Significant changes to error code handling or response structures

Policy: Backward-incompatible changes will typically result in a new Major API Version (e.g., from v2.0 to v3.0). We will provide advance notice and migration guidance for such changes. For example, the upgrade from Buzz API v0.5 to v2.0 was a non-backward-compatible change that required users to re-architect their integrations.

Backward-Compatible (Non-Breaking) Changes

These are changes that should not break existing client integrations. Clients should be designed to gracefully handle these types of modifications. Examples include:

  • Adding new API endpoints or resources
  • Adding new optional request parameters or fields to existing API endpoints
  • Adding new fields to API responses (clients should ignore unexpected fields)
  • Adding new values to an existing enumeration (clients should handle unknown enum values gracefully)
  • Bug fixes that do not alter existing documented behavior in a breaking way

Note: Certain scenarios require the API to be tweaked for consistency or best practices. This may result in a non-substantial breaking change. For example, adding the following rule tightens validation on a field:

The name must be a non-empty string.

Previous Behavior:

POST /v2/campaigns 
Content-Type: application/json 

{ 
  "name": "",            // empty name was accidentally allowed 
  "budget": 5000, 
  "startDate": "2025-06-01" 
}

Response:

HTTP/1.1 200 OK 
Content-Type: application/json 

{ 

  "id": "abc123", 
  "name": "", 
  "budget": 5000, 
  "startDate": "2025-06-01", 
  "status": "CREATED" 
}

New Behavior:

POST /v2/campaigns 
Content-Type: application/json 

{ 
  "name": "",            // now violates the new validation rule 
  "budget": 5000, 
  "startDate": "2025-06-01" 
} 

HTTP/1.1 400 Bad Request 
Content-Type: application/json 

{ 
  "error": { 
  "code":  "INVALID_PAYLOAD", 
  "field": "name", 
  "message": "Campaign name must be a non-empty string."
  } 
}

Why this is not a substantial breaking change

  • Intent: We’re fixing a payload-validation bug (campaigns without names should never have been allowed).
  • Impact: Clients sending empty names will now get a clear validation error (400) instead of an opaque success.
  • Policy takeaway: Even though the HTTP status changed (200 → 400), because we’re enforcing a rule that was always supposed to exist, we treat this as a non-substantial (minor) break—suitable to roll into a “minor” version bump (V2.0) rather than a full “major” bump. Changes within this category will be communicated via the changelog.

Policy: Backward-compatible changes may be introduced within the currently active major API version (i.e. v2). Buzz API v2 is the only active version of the API. While Buzz 0.5 is still available, it is deprecated. Such changes will be documented in our changelog.

API Version Lifecycle and Support

API versions will transition through several lifecycle stages:

Version Statuses

  • Active (Recommended): The most current, fully supported major API version (v2). This version receives all new features, improvements, and bug fixes. Buzz API v2.0 is the current active and recommended version.
  • Deprecated: An older API version that is still supported for a limited time but is no longer recommended for new development and will not receive new features. Clients should plan to migrate to the Active version. For example, during the rollout of Buzz API v2.0, the v0.5 API was supported to allow for a transition period.
  • Sunset/End-of-Life (EOL): An API version that is no longer supported. Requests to a sunsetted version may fail or be automatically routed to a newer version if explicitly stated. Integrations must be migrated to an Active version before the EOL date. For instance, the v0.5 reporting APIs have been fully deprecated and replaced by the v2.0 Reporting API.

Support Commitment & Deprecation Notice

  • Support Duration: FreeWheel is committed to supporting an Active major API version for a reasonable period after a subsequent major version is released. We aim to provide at least 12 months of support for a major API version after it enters a "Deprecated" status following the release of a new major version.
  • Deprecation Notice: We will provide a minimum of 6 months' notice before an API version is officially moved to "Sunset/End-of-Life (EOL)" status. This notice will be communicated through our official channels (see Staying Informed: Communication and Documentation below).

Specific timelines for support and deprecation will be announced with each new major version release.

Staying Informed: Communication and Documentation

We are committed to keeping you informed about API changes. API changes will be communicated through the following avenues:

Changelog

The API changelog is the primary and most current source of information for all API changes, including new features, updates, improvements, and deprecations. We encourage you to monitor the changelog regularly.

Developer Portal & API Documentation

The Developer Portal, including the API Reference and guides, will serve as the canonical source for:

  • This API Versioning Policy.
  • Detailed documentation for all supported API versions.
  • Information on version-specific features and behaviors.

Migration Guides

For major API versions that introduce backward-incompatible changes, we will provide comprehensive migration guides. These guides will detail the changes, explain the impact on existing integrations, and offer step-by-step instructions to help you upgrade to the new version. A migration guide was provided for the transition from Buzz API v0.5 to v2.0.

Other Communications

Significant announcements, such as the release of new major versions or impending EOL dates, may also be communicated via email to registered developer contacts or through other official Freewheel channels.

Your Responsibilities as an API Consumer

To ensure a smooth experience with the Buzz API, we encourage you to:

  • Stay Updated: Regularly review our changelog and Developer Portal for the latest API information.
  • Use Active Versions: Plan to migrate your applications to Active (Recommended) API versions in a timely manner, well before older versions reach their EOL date.
  • Build Resilient Integrations: Design your applications to handle API responses gracefully, such as by ignoring unknown fields and accommodating new enum values, to minimize the impact of non-breaking changes.
  • Test Thoroughly: Before switching your production environment to a new API version, thoroughly test your integration in a development or staging environment. You may utilize your sandbox environment to test new migrations at https\://{BUZZ_KEY}sbx.beeswax.com/

Policy Updates

FreeWheel reserves the right to update this API Versioning Policy from time to time. Any significant changes to this policy will be communicated through our official channels, and the "Last Updated" date at the top of this document will be revised.

We appreciate your partnership in building innovative solutions with the Buzz API. For questions regarding this policy, please contact our support team.

Updated about 19 hours ago

What’s Next

Related Documents