API 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.

Release Calendar

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.

• July 2018 - 1.3.0
• Oct 2018 - 2.0.0
• Jan 2019 - 2.1.0
• Apr 2019 - 2.2.0
• July 2019 - 2.3.0
• Oct 2019 - 3.0.0

Deprecation Calendar

We deprecate once a year in October (when we release the new major version). Each 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 2018

  • API version 2.0 was released to General Availability
  • All APIs under 1.x.x were marked deprecated (e.g. 1.0.0, 1.1.0, 1.2.0, 1.3.0)

• 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 - All APIs under 2.x.x will be deprecated (e.g. 2.0.0, 2.1.2, 2.3.0, etc. including all patches)

  • API version 4.0 will be released to General Availability
  • 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)
  • 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)

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.

Prior to being released to General Availability, Blend's APIs are Experimental. The Experimental API borrows from the GA APIs Semantic versioning. For example if the currently released version is 2.0, then the Experimental versions will start at the next minor version up for release, v2.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, the Experimental APIs can make any changes, any time without announcing it or changing their version number.

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.

Specifying a Version

You can select which version of the API you are using by passing the Blend API Version Header (Blend-Api-Version) in the request. You should always specify a version in the request to ensure that the release of new versions of the API will not negatively impact your integration. Learn more about how to use the version header to maintain access to your needed functionality in the Quick Start Guide.

Types of Changes

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

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

FAQs

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 15, 2018 - Oct 15, 2019 will be usable until Oct 15, 2020). Depending on how often your team releases/updates existing integrations, you can begin transitioning a year in advance. However, new functionality is only provided to the latest API versions.

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.

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