API Release Process – Blend Help Center

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 developers can have enterprise-level API stability for production code.

Versioning Schema

Blend uses Semantic Versioning, which 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.

Patches

Most patches will only be made available to the release version. Occasionally, some critical patches (pertaining to legal, compliance, or security) will be made available to all versions. Patch versions will be deprecated at the same time as the major or minor release version that it is attached to (e.g. ‘4.2.1’ will be deprecated at the same time as ‘4.2.0’ and ‘4.0.1’ will deprecated at the same time as ‘4.0.0’)

Release Calendar

Blend has scheduled API releases (major or minor) once every quarter. Below is the release calendar for the upcoming year.

July 2018 - 1.3.0
Nov 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

Each version will be available for at least 1 year from release, giving developers sufficient time to update to newer versions. We deprecate once a year. Below is the deprecation calendar for the upcoming years.

November 2018 - All APIs under 1.x.x will be deprecated (e.g. 1.0.0, 1.1.0, 1.2.0, 1.3.0)
October 2020 - All APIs under 2.x.x will be deprecated (e.g. 2.0.0, 2.1.2, 2.3.0, etc)

Specifying a Version

The API version can be selected by passing a header in the api request. We default the version header to the latest released version of the API for convenience while you are building an integration. However, you should always pass the version header when the integration is deployed to production, as the default version will change as old versions are disabled.

Types of Changes

Every API improvement has a different level of urgency and impact, so Blend treats them differently. See Figure 1 for more details.

Figure 1: Change Details

Name & Description	Bump Type	Applied Versions	Examples
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	Changing all MISMO endpoints as HMDA 2018 becomes regulation
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

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 un-deprecated 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.