When adding new capabilities or changes to existing API products, we employ a set of policies and principles that are based on industry standard practices.
These API policies and principles are subject to change from time to time by Blackhawk Network at its discretion.
Blackhawk Network versions APIs using major and minor version numbers.
The major version number will increment when a breaking change is introduced. Examples of breaking changes include:
- Changing the format of a response object in a way that would break an existing implementation
- Changing the required headers
- Significant functionality additions or removals
Minor version numbers are reserved for enhancements and non-breaking tweaks to existing API versions. Not all changes will result in a new version number. Examples of non-breaking changes include:
- Adding new functionality
- Adding new parameters to response objects
An API is backwards compatible when there is a change to the API and the updated API continues to work the same way with the partner application without any modifications.
If it is necessary to change an API representation in a way that is not backwards compatible, we create a new major version of the API. The old version will continue to be supported in accordance with the end-of-life policy described at the end of this document. Note that we may change the behavior of an API at any time without prior notice for any reason, including if the existing behavior is incorrect or constitutes a security-related vulnerability.
Always use the robustness principle of “be conservative in what you send, be liberal in what you accept” when using the APIs.
- If a REST API returns an attribute, then it will continue to be returned with the same name, and the same value type (that is: string, number, array, or object).
- If that value is a list, the type of the contents of the list will not change.
- If the value is an object, that object will satisfy the same compatibility guarantees as the document as a whole.
- If an attribute has a primitive type and the API documentation does not explicitly limit its possible values, partners must not assume the values are constrained to a particular set of possible responses. For example, do not assume an attribute is an enumerated type and that other values cannot be added at a later time.
- If an attribute of an object is not explicitly declared as mandatory in the API, partners must not assume it will be present.
- New attributes may be added to a representation at any time, but any new attributes must be optional and cannot alter the meaning of an existing attribute.
- If an attribute of an object is a URI, then the resource identified by that URI must maintain the same compatibility guarantee.
When we version an API, we change the major version number of that API and typically that means we do not allow for backwards compatibility to be maintained. We may also periodically make minor releases to an API that do not change the major version number. These changes are backwards compatible.
- We will support all major versions of each API according to our end-of-life policy (EOL) which may apply to the oldest API version when a new major version is launched.
- A major version is generally created based on customer requirements, market needs, or technology shifts that influence an upgrade or necessary migration, and will be released according to a roadmap.
- A major version provides significant technology upgrades that generally deliver compelling value.
- Minor releases to an API provide enhancements to drive new business value or bug fixes that can be delivered without major technological or architectural changes to the API.
- Minor release development is not guaranteed on all major API versions.
A major version of an API does not have an indefinite life period and we will end-of-life (EOL) a major version for business or technical reasons at our discretion. When a major version of an API reaches EOL, we will communicate the change through the relevant Developer Portal or other means to endeavor to give clients and partners time to update applications.
- A release of a new major version signals a review of the oldest major version of an API to be deprecated in 24 months.
- An API going through EOL will receive only mandatory minor enhancements where there are significant defects that result in financial loss.
To keep clients and partners informed of changes to APIs, Blackhawk Network will communicate the release of new major API versions through the relevant Developer Portal and/or through other communication channels. It is our intention is to give clients and partners the opportunity to alter their code to take advantage of the new versions.
Client and Partner communication will take place for each minor release with release notes posted on this Developer Portal.
Updated almost 3 years ago