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:
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)
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)
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)
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.
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.
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.
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.
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.
|Name & Description||Bump Type||Applied Versions||Examples|
|**Experimental Changes** Changes to endpoints and schemas still in the Experimental version of the API.||No version bump.||Newest Experimental version only||Rolling updates to the Lender endpoints to work out the bugs in automatically adding LO users in beta|
|**Security, Performance, or Functional Patches** Changes that improve security, performance, or broken functionality of the API – no impact on schemas.||No version bump.||Available to all versions.||Database upgrade, security patch, resolving 500 errors.|
|**Schema Bugfixes** Updates that fix a bug by changing an endpoint schema, but are not critical (legal, compliance, or security).||Patch bump (ex: 1.2.1 -> 1.2.2)||Available to the release version only||Fixing a typo in an ENUM in an API response.|
|**Critical Schema Bugfixes** Updates that fix a bug by changing an endpoint schema, and are critical (legal, compliance, or security).||Patch bump (ex: 1.2.1 -> 1.2.2)||Available to all versions||Updating MISMO endpoints to be HMDA 2018 regulation compliant|
|**Minor Release** Releasing schema improvements, new functionality, or new endpoints.||Minor bump (ex: 1.2.1 -> 1.3.0)||Available only in new release version||Adding a borrowerId to a field to improve tracking, adding a new endpoint for MISMO download.|
|**Major Release** Deprecating endpoints or resources||Major bump (ex. 1.2.1 -> 2.0.0)||Available only in new release version | Consolidating two endpoints, removing functionality||Consolidating two endpoints, removing functionality|
## What's considered a breaking change?
**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)
**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.