← API

External API Stability Ratings

Context and Problem Statement

Many, if not most, consumers of the external API (e.g. 3rd party developers) will focus on stability and risk minimization. They will therefore avoid or migrate away from APIs that have been deprecated per the External API Deprecation policy.

However, some consumers of the external API will be interested in taking on more risk in exchange for gaining an advantage in the market (e.g. being first to market with a solution).

How will we manage the concerns of both types of developers?

Decision Drivers

  • Stability and predictability for consumers of the API that value those attributes.
  • Potential for higher rewards for consumers of the API that can take on more risk.
  • Reduced support cost of the API for Banno/Jack Henry.

Decision Outcome

Chosen option: Introduce External API Stability Ratings, with an Experimental Rating.

This provides a balance between the need for some consumers of the external API to have stability and minimize risk with the need for other consumers of the external API to take greater risks for the potential of higher rewards.

Consumers of the external API can select a version of the API with a Stability Rating that fits their business needs and appetite for risk.

This also balances the need for Banno/Jack Henry to keep API support costs at a manageable level.

Considered Options

  • Introduce External API Stability Ratings, with an Experimental Rating
  • Modify Deprecation Policy to Include Experimental Status
  • Continue the Status Quo

Pros and Cons of the Options

Introduce External API Stability Ratings, with an Experimental Rating

For this option, we would introduce the concept of a Stability Rating for the external API. More specifically, particular versions of the external API would be given one of three, mutually exclusive stability ratings:

  • Experimental: This version of the API is for ‘bleeding-edge’, in-development use cases. There is little to no support or warranty for this version of the API. The API’s endpoints, requests, and responses may be added, changed, or removed altogether without warning.
  • Stable: This is the version of the API that is currently supported.
  • Deprecated: This is the version of the API that has been deprecated per the External API Deprecation policy.

For example, we may have these hypothetically different API versions available at once. In this example, we would mark in our developer documentation as such:

  • /vNext - This version of the API is Experimental and subject to change without notice (including removal of the API as a whole or in part).
  • /v1 - This version of the API is Stable and currently supported.
  • /v0 - This version of the API is Deprecated and scheduled for EOL (End-of-life) on YYYY-MM-DD.
  • Good, because it gives us more flexibility to communicate the stability and risk profile for the external API.
  • Good, because this aligns nicely with the existing deprecation policy. The answer to ‘is this API something that I can rely upon, or is it going away’ will be based on whether the developer selected a deprecated API (that is subject to the deprecation policy), a stable API, or an experimental API.
  • Good, because the addition of the Stability Rating does not incur very much additional communication responsibilities.
  • Bad, because we will have to be diligent in communicating the risks assumed by consumers of the external API that decide to use the Experimental option.

Modify Deprecation Policy to Include Experimental Status

For this option, we would modify the existing deprecation policy to include a special Experimental case. It would imply little to no support or warranty for this version of the API.

In effect, the Experimental status would end up being the equivalent of the Drop Support Without Warning from the “Considered Options” in the External API Deprecation policy.

  • Good, because it gives us more flexibility to communicate the stability and risk profile for the external API.
  • Bad, because it is less clear to consumers of the external API if a particular version of the API fits their business needs and appetite for risk.
  • Bad, because it complicates the existing deprecation policy. We would have two different answers to the question ‘is this API something that I can rely upon, or is it going away’. Developers would have to understand that there is a ’typical’ deprecation case and a ‘special’ deprecation case.

Continue the Status Quo

For this option, we would not have to do anything.

  • Good, because there aren’t any changes that would need to be made or communicated.
  • Bad, because this doesn’t meet the needs of consumers of the external API that are willing to take on more risk for the potential of higher rewards.