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.
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.
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.
- 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.
- 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|
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.|
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 |
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.|
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:
- 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.
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.
Updated over 1 year ago