Versioning of APIs

Bubblehouse is evolving quickly, but our general policy is to avoid churn. We want to allow you to adopt platform changes (1) gradually over time and (2) on your own timeline.

Per-function and global versioning

In general, all our APIs use per-function versioning (SomeCall3), and most APIs also have API-wide global versioning (v20230101).

Per-function versions allow you to upgrade individual function calls on your own time, and avoid forcing you to do all upgrades at once when bumping a single version number. We try to keep old call versions available to you for as long as reasonably possible.

Global versions (when present) are date-based (v20230101) and relate to cross-cutting concepts like authentication and error response formats, and serve two goals:

1. Allow you to upgrade shared API calling code on your own time.

2. Disable access to functions deprecated before that date, so that when you do want to be up to date, you can quickly ensure that you're not calling any outdated functions.

   (E.g. if you're using January 2023 API version, you won't have access to calls deprecated in 2022.)

Normally, your entire codebase should strive to use the same global version for the sake of sanity, but that's not a requirement.

Versioning of RPC APIs

RPC APIs use per-function versions (SomeCall3) and global versions (v20230101) specified as part of the URL.

Versioning of Blocks API

Blocks API uses per-block versioning (Rewards2) and global versioning (v20230101) specified as part of the URL. This is very similar to RPC APIs.

Versioning of Block Client API

Block Client API uses per-function versioning ({bubblehouseBlockClientCall: 'Resize1').

You're not free to pick which version to implement, though; each specific version of the block will call specific versions of Block Client API functions.

There's no explicit global versioning for these calls; we do not anticipate needing a new communication protocol, but if we ever do, we'll change the bubblehouseBlockClientCall part. (Another way to think about global versioning of Block Client API is that it's implicitly tied to the global version of the Blocks API.)

Versioning of Hooks API

Individual hooks have version numbers (CreateDiscount4). Because you explicitly specify which hooks you're subscribing to, you're also specifying the desired version numbers.

You can subscribe to multiple versions, too: CreateDiscount3 CreateDiscount4, and we'll call all of them, in case you're gating a version transition by a feature flag on your end.

There's a single global hooks API version specified on the API details page. Historically there's been very little reason to change it.

Learning about API changes

We track which API functions and versions our customers use, and will contact you in advance if any deprecations or forced migrations are on the horizon.

We'll also contact you when we release new versions of the calls in the areas relevant to your loyalty program.