Stability

Stability is extremely important for developers building on any developer interface. At the same time Benchling, like any other software, requires iteration and change over time. This document is intended to set expectations and to inform how a given API endpoint, Warehouse table, or Event should be used and in what environments, in order to accommodate the need for stability and backwards compatibility as we make changes.

Are breaking changes made to the API, Warehouse, or Events?

Generally no, but there are some exceptions. We do everything we can to keep our interfaces stable to keep from breaking our customer's integrations and apps that are built on top of them.

If introducing a breaking change is absolutely necessary, we will give somewhere between 6-12 months of lead time to allow customers to adapt/migrate when we are making a breaking change. 6 months is for small changes such as a single field rename, and up to 12 months for major changes such as a significant rework on an endpoint or table, or migration to a new endpoint or table.

There are sometimes bugs that qualify as exceptional circumstances where we will make changes immediately, without providing a deprecation period, such as:

• If a bug has been exploited to provide capability that is not intended to be supported, it will be patched and will not follow this process.
• If a bug causes a significant performance issue, it will be patched and will not follow the process.

Endpoints and tables tagged as alpha or beta do not fall under this guidance. See next section for details on these endpoints.

What do alpha and beta mean in the API, Warehouse, and Events?

When we are actively iterating on functionality in the API, Warehouse, and Events systems, we often want to expose new functionality before we finish iteration to get feedback from our users. When an endpoint, table, or event is in alpha or beta, it means we aren't 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. Expectations for each are listed below.

Expectations for beta endpoints and tables

Generally, we bring an endpoint, table, or 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 aren't frequent. We give a 30 day deprecation period prior to removing the old behavior.

These endpoints, tables, or events are mostly locked in, but we might have to slightly change it due to a variety of reasons. We don't recommend using these for production use cases unless you are closely monitoring the use and ready to adapt on short notice if necessary.

As an example, we’ve really only utilized this to change the name of endpoints, tables, and events or specific fields in the payload. We haven’t previously made large architectural shifts while in beta.

Warehouse beta tables are marked by having $beta in the table name. Example:

benchling.bnch$table$beta

Expectations for alpha endpoints and tables

Endpoints, tables, and events in alpha are essentially ideas that we are debating. We can make breaking changes to these at any time without warning, and can remove the functionality they provide entirely. This is our space to give access temporarily for the purposes and gaining a better understanding of the use case, functionality, and format.

You should not use alpha endpoints, tables, or events for anything other than testing and evaluation. We highly encourage you to provide feedback on them, as it is the most impactful time to do so!

Warehouse alpha tables are marked by having $alpha in the table name. Example:

benchling.bnch$table$alpha

What about the Benchling SDK?

The Benchling Python SDK obeys Semantic Versioning, meaning that breaking changes will only be made when a new major version is released. Because it's possible to "pin" a specific SDK version, Benchling releases major versions of the SDK much more frequently than with the API & Events. Regardless, we do everything we can to keep the SDK's interfaces stable between versions.

The Benchling SDK also includes support for some alpha and beta APIs. While Benchling makes no guarantees that alpha or beta APIs will be implemented in the SDK before their promotion to stable, any such services follow the same minimum breaking change warning as their corresponding alpha or beta API. Because SDK support tends to lag slightly behind API releases, breaking changes that are made to the API may not be reflected in the SDK until the next major version.

What does “deprecated” mean?

When we deprecate something in our developer platform, that means we are indicating that we plan to stop supporting the functionality (removing the field, parameter, event, or endpoint) in the future. It does not mean we are stopping support for it immediately. It allows us to indicate that developers should start planning how to adapt and that they should add the solution into their planned future work. If it’s a stable endpoint or event, as in it’s not in beta or alpha, that means developers should plan to do so in the next 6-12 months. If it’s in beta, developers should plan to do so within 30 days.

Prior to the end of the deprecation period, the endpoint, event, or functionality is fully supported. Nothing will suddenly change, except for alpha endpoints.

When starting a new project, deprecated features should be avoided entirely.

How will we notify of Breaking Changes?

We’ll notify of changes in some combination of a few channels:

1. We’ll post them in our regular product release notes (reach out to [email protected] if you are not subscribed) as well as the Benchling Developer Changelog
2. We’ll reach out to customers that are using the affected endpoint directly.

Timelines quoted above will be included in the release notes and when we reach out directly.