APIs represent system to system interaction channels for Equifax products. So while the technique to upgrade versions is specific to API best practices, the upgrade and deprecation of an API really touches the life cycle of product enhancements. 

 

Equifax’s API lifecycle and deprecation policy:

  1. Equifax follows industry standard practices in defining major and minor versions:
    1. Major version: The major version indicates to API consumers that significant changes have occurred in the API contract from a previous version. A significant change may or may not be backward compatible.
    2. Minor version: The minor versions are backward compatible changes to the API contract. 
  2. Equifax will add a major version to an API only because of industry changes, security/compliance changes or when a feature/modification is introduced to support the request of multiple customers to provide enhanced features in the market. A major version may significantly restructure, remove or rename a data structure or one of its members, add a new interface to an existing API, or change a default setting.
  3. Equifax will announce the release of the next major version 3 months in advance.
  4. External customers will have a reasonable time (18 months) to migrate off of the deprecated version.
  5. Internal customers will have 6 months to migrate off of the deprecated version.
  6. Minor versions are backward compatible and do not have set sunset rules. Equifax will notify customers about backward compatible minor version changes ahead of time.

Note: External customers, please refer to your contract for details on this agreement and compliance.


 

Engineering Handbook guidance

General guidance on API versioning approach  -  https://confluence.equifax.com/display/EBG/Architecture+Guidelines#ArchitectureGuidelines-9APIVersioningandBackwardCompatibility

This section contains general information on API versioning and a definition of Major and Minor versions. To recap:

  • Major version number: The major version number is a required numeric integer value indicating to an API consumer when significant changes to an API have occurred from a previous version. A significant change may or may not be backward compatible.
  • Minor version number: The minor version number is a required numeric integer value indicating to an API consumer that minor changes to an API have occurred from a previous version. Although these changes are guaranteed to be backward compatible by the service, a consumer could use the API in a way that breaks their own compatibility.
  • Additional version, build or release numbers: Optional alphanumeric value(s) indicating a specific set of artifacts are a part of this version of software. This portion of the version number has no relevance to the backward compatibility by the service. Two versions with the same major and minor version numbers are both functionally identical service APIs.

API deprecation topic in EHB - https://confluence.equifax.com/display/EBG/Architecture+Guidelines#ArchitectureGuidelines-9.6.1Discussion 

This section describes the need for services to have deprecation and sunset rules but leave the specifics to individual service. The challenge is that customer contracts are beginning to include API versioning details. So we need a standard language for inclusion in the contract.

 

DevPortal API Versioning Guidance

<br>