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.

Oct 2020: 4.0.0
Jan 2021: 4.1.0
April 2021: 4.2.0
August 2021: 4.3.0
January 2022: 5.0.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

When marking versions of the public API as deprecated, Blend will deprecate all of the versions that fall under the same major version at the same time. After versions have been marked deprecated, Blend reserves the right to drop support for any or all endpoints that were previously available. Once versions are no longer supported they will be referred to as removed.

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.
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.0, then the Experimental versions will start at the next minor version up for release, v3.1.0.

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.

Removed

These endpoints will return 404's or other error codes and will not work.

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
Enum Value Backfilling This type of change is when Blend adds valid values to enums. When this happens, objects with these new values for the enums will also be returned by older versions of the API that might not have contained those values in the enum at release.	No version bump.	Available to all versions	The `type` enum for the `documents` resource is constantly being expanded. The `GET /documents` endpoint will return these new document types in the response for every existing version of the API including ones released before the new values were added.
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

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:

Adding or 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. After an API has been marked deprecated, it will remain available for at least 6 months but is subject to removal after that period.

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 the release process or schedule at any time. Please refer to the Blend SLA for additional details and guarantees.