Stability | Benchling In Vivo

Stability is extremely important for developers building on any developer interface. At the same time, Benchling In Vivo, like any other software, requires iteration and change over time. This document sets expectations and informs how a given API endpoint or Webhook event should be used and in what environments, to accommodate the need for stability and backwards compatibility as we make changes.

What does Beta mean?

When we are actively iterating on functionality in the API and Webhook events, we often want to expose new functionality before we finish iteration to get feedback from our users. When an endpoint or event is in beta, it means we are not entirely sure if this is how we want to reflect the data model or expose the functionality, and we want the flexibility to keep iterating before moving to general availability (GA).

Beta

When APIs are first released, they are available at the /api/public/v1-beta/ path. Customers are encouraged to provide feedback on beta endpoints as we iterate.

Generally, we bring an endpoint or Webhook event into beta because we know we want to have the functionality, but we still want the flexibility to change models. Breaking changes happen more than normal, but are not frequent. We provide a 30-day deprecation period prior to removing old behavior.

Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. The latest version is 2022-12-14.

All requests use your API key settings, unless you override the API version.

To set the API version on a specific request, send a X-Studies-Api-Version header.

Your API version controls the API and webhook behavior you see (for example, what properties you see in responses, what parameters you’re permitted to send in requests, and so on). Your version gets set when you create your API key. When a breaking change is introduced to the Benchling In Vivo API, a new dated version is released. To avoid breaking your code, we don’t change your version until you’re ready to upgrade.

Each webhook listener is configured with a specific API version. If you wish to change the version of your webhook events, contact support.