V3 Stability Guidelines
This guide provides an overview of the guarantees that Benchling makes for public developer interfaces and how breaking changes are communicated.
Public API
Our v3 public API has two stability levels, stable and beta. As a general rule, these stability levels are aligned to the product’s current state. A product or feature that is generally available will typically have a stable public API, while products and features in (open or closed) beta or Limited Availability expose beta endpoints.
Here is what to know about developing with stable and beta endpoints:
Breaking changes to stable endpoints are rare. We only break stable interfaces when absolutely necessary. Breaking changes typically fall within one of these categories:
- Deprecation of legacy functionality
- Significant feature redesign
- Security vulnerability
- Bug fix
* The standard notice period is 90 days. The only allowed exception is urgent security and bug fixes where waiting 90 days to release the change is not acceptable.
** Beta endpoints may change at any time without notice.
For beta endpoints, we reserve the right to make breaking changes at any point without notice. beta endpoints leverage pre-GA products. The ability to iterate quickly is vital to making a new product stable and generally available quickly. We do not recommend using beta endpoints on production environments. We do encourage using and testing these APIs and giving feedback to the Benchling product team (in the Benchling Community or via your account team).
Events
Events (delivered over webhooks) are pinned to the most recent version of an object. For example, if object A is stable, its corresponding event is also stable; if object B is in beta, its corresponding event is also in beta.
The same breaking change guidelines apply.
Benchling SDK
The V3 Python SDK obeys Semantic Versioning, meaning that breaking changes will only be made when a new major version is released.
SDK releases happen frequently but not on a set schedule. When new endpoints or features are available, a new SDK version is released. Follow our changelog to be notified of new releases.
Benchling MCP
The Benchling MCP obeys Semantic Versioning, meaning that breaking changes will only be made when a new major version is released.
Non-breaking updates (new tools, improved descriptions) do not require a new version.
Frequently Asked Questions
How will I be notified of breaking changes?
We aim to reach as many developers as possible when communicating breaking changes. We guarantee to always use these channels:
- Changelog: we recommend subscribing to the RSS version of the changelog. Out-of-the-box RSS feed integrations can be used to broadcast updates to internal Teams or Slack channels.
- Benchling Community: a place where we advertise Open Beta programs and collect feedback. Not typically used to communicate breaking changes but a place to learn about new features before they are generally available.
In some cases, you may hear directly from your account team if you have been identified as being impacted by a breaking change that is not (yet) more broadly communicated.
We monitor usage, provide migration guidelines, and work directly with customers who need help migrating off of breaking functionality.
All breaking changes are communicated with clear guidelines and timelines for migrating off of breaking functionality.
What counts as a breaking change to the V3 REST API?
In general, this guidance applies to the following backward-incompatible changes:
- Removing or renaming an endpoint
- Removing or renaming a response field
- Widening the type of a response field (e.g. non-nullable -> nullable)
- Adding a new required field to a POST/PATCH request body or making an optional field required
- Narrowing the type of a request field
Note that we consider the following changes not to be breaking and expect third-party integrations to be resilient to them:
- Adding a field to a response
- Adding a new member to an enum
- Changing the text of an error message
What does it mean if an endpoint, field, or event is marked as “deprecated”?
We use deprecated to indicate that we intend to stop supporting a specific feature in the near future. As a general rule, the Benchling Product team will work with impacted customers and decide (depending on the blast radius and complexity of the breaking change) how much time to provide to migrate off of deprecated functionality.
What happens when a beta endpoint is promoted to stable?
Once an endpoint is promoted to stable, the beta tag is removed from the API reference and it will immediately become available to all users in the stable API.
How can I use a beta endpoint?
Beta endpoints are open to everyone. Your API request needs to include the beta opt-in header, EARLY-ACCESS: true.