Release Process

Overview

The Blend API team regularly updates the Public API with new features, bug fixes, and performance improvements. This release process enables Blend to improve and iterate quickly while ensuring that Integrators can have enterprise-level API stability for production code.

Major & Minor Version Release Schedule

Blend has scheduled API releases for major and minor versions that occur every quarter. Below is the release calendar for the upcoming year. Major versions are released once a year in October.

• Oct 2019: 3.0.0
• Jan 2020: 3.1.0
• April 2020: 3.2.0
• July 2020: 3.3.0
• Oct 2020: 4.0.0
• Jan 2021: 4.1.0
• Apr 2021: 4.2.0

Versions are always released on the last day of the month unless that day falls on a Friday, Saturday or Sunday. In that case, the version will be released on the Thursday before the last day of the month.

Major Version Deprecation Schedule

Blend deprecates previous version of the API once a year in October at the same time we release the new major version. Each major version will be available for at least 1 year from release, giving Integrators sufficient time to update to newer versions.

Below is the deprecation calendar for the upcoming years:

• October 2019

  • API version 3.0 will be released to General Availability
  • All APIs under 1.x.x will be fully deprecated and removed (e.g. 1.0.0, 1.1.0, 1.2.0, 1.3.0)
  • All APIs under 2.x.x will be marked deprecated (e.g. 2.0.0, 2.1.2, 2.3.0, etc. including all patches)

• October 2020

  • API version 4.0 will be released to General Availability
  • All APIs under 3.x.x will be marked deprecated (e.g. 3.0.0, 3.1.0, 3.2.0, 3.3.0, etc. including all patches)

• March 2021

  • All APIs under 2.x.x will be fully deprecated and removed (e.g. 2.0.0, 2.1.0, 2.2.0, 2.3.0)

• October 2021

  • API version 5.0 will be released to General Availability
  • All APIs under 3.x.x will be fully deprecated and removed (e.g. 3.0.0, 3.1.0, 3.2.0, 3.3.0)
  • All APIs under 4.x.x will be marked deprecated (e.g. 4.0.0, 4.1.0, 4.2.0, 4.3.0, etc. including all patches)

Versioning Schema

Blend uses Semantic Versioning for our public APIs once they reach General Availability. Semantic Versioning means that every version that we release will be formatted as MAJOR.MINOR.PATCH (i.e. '4.2.1'). By definition:

• The major version is incremented when Blend makes incompatible API changes. Major versions are released once a year in October.
• The minor version is incremented when Blend adds functionality in a backwards-compatible manner. Minor versions are released three times a year, one for every quarter except for Q4 (when there's a major release).
• The patch version is incremented when Blend makes backwards-compatible bug fixes. Patch versions can be released at any time.

Experimental Versions

Prior to being released to General Availability, Blend's APIs are Experimental. The Experimental API version number is based on the version number of the currently General Availability API.

For example if the currently released version is 3.0, then the Experimental versions will start at the next minor version up for release, v3.1.

However, Experimental versions follow no versioning rules internally or versioning SLAs. They are meant as a sandbox for Blend's Integrators to add, try out and harden new functionality, and occasionally make it available to customers on an early access basis before it is released.

Whereas the General Availability versions have to announce their changes with a major, minor, or patch version bump and release communications, the Experimental APIs can make any changes at any time without announcing it or changing their version number.

Specifying a Version

You can select which version of the API you are using for any individual call by passing the Blend API Version Header (blend-api-version) header in your requests.

For more information see API Technical Standards or the Quick Start Guide.

Versioning Terminology

General Availability

• The most recent "released" version, as opposed to the Experimental, "unreleased" version.
• The functionality in this version stable, robust, and fully supported. It is meant for production use by our customers and partners.
• Released versions do not have "(Experimental)" after their name on Blend's API docs.

Experimental

• The most recent version(s) that has not yet been released.
• Blend follows no deprecation schedule, breaking change rules, or SLAs for bug fixes to this functionality before it are released.
• It can be changed at any time without warning or even removed entirely. It may not work at all, may not be fully tested, or may fail often.
• Not intended for production use unless otherwise noted as "Stable". Long term support should not be assumed for fields/params/functionality in this state.

Stable

• Consider this "Early Access" to API features.
• Some functionality in the Experimental version may be locked-in, but hasn't had a chance to be released yet.
• Stable functionality is intended to remain in the API for future releases, regardless of which branch it's currently in.
• Blend will still not follow a deprecation schedule, breaking change rules, or SLAs for bug fixes to this functionality until it is are released unless otherwise specified.

Deprecated

• This functionality will not be developed any further, and support will be limited to compliance/security bugfixes.
• Customers/partners should actively be moving away from using this functionality because it will be fully deprecated and removed within the next year.

Removed

• This functionality has been entirely removed from our API. New versions will not have to guarantee backwards compatibility to this version and support will not be able to support customers/partners using this version.
• Usually this will occur as part of a major release deprecation, 1 year after the version was marked deprecated.
• Sometimes exceptions will occur for Critical issues with the API like security, compliance or legal issues. In these cases Blend will prove transition support.

Types of Changes

Every API improvement has a different level of urgency and impact, so Blend treats them differently.

FAQs

What's considered a breaking change?

Breaking

In the Request:

• Removing routes (including by removing url params)
• Removing existing fields from schemas (query or post body)
• Removing valid values for fields (from an enum)
• Changing the types of fields (string => int) (string => array)
• Requiring a field that was previously not required

In the Response:

• Removing fields from response
• Changing type of field (string => int) (string => array)

Non-breaking

In the Request:

• Adding new routes (including by url params)
• Adding new valid params to the schema (query + body)
• Adding new valid values to enumerated params
• Making a required param optional

In the Response:

• Removing valid values from enumerated fields

How will new versions be communicated?

All new versions will be communicated via our Standard Release Notes Process.

For how long can I use the same fixed schema version?

All released APIs are available for at least 1 year. You can use any released version until the October of the following year (e.g., APIs released between Oct 31, 2019 - Oct 31, 2020 will be available until Oct 31, 2021).

Depending on how often your team releases/updates existing integrations, you can begin transitioning to the next major version of the API a year in advance of the current version's deprecation date.

What is your internal process for testing changes before they are released to the Public API?

All changes undergo thorough testing and validation before being enabled in any user facing Environment. All changes require a detailed specification, implementation plan, and test plan before development begins. As part of development, automated unit, integration, and end-to-end tests are built as appropriate, with automatically enforced code coverage. New features are broken down into small incremental changes, and undergo in-depth code review before they can be merged into the master code repository. Once merged, changes undergo additional manual and automated testing to ensure the feature is implemented according to the specification and does not introduce any unintended regressions to any currently supported version. Before new code is deployed to any user facing site, all existing automated and manual tests must pass.

Legal Stuff

^ Blend reserves the right to change this schedule at any time. Please refer to the Blend SLA for additional details and guarantees.