Context and Problem Statement
Consumers of the external API (e.g. 3rd party developers) need stability so that they aren’t constantly ‘chasing’ changes to the API.
On the other hand, it is likely not feasible for Banno/Jack Henry to support a particular version of the API in perpetuity.
What is the deprecation policy for the external API?
Decision Drivers
- Stability for consumers of the API
- Predictability for FIs (financial institutions) to schedule software changes (commonly with software vendors).
- Reduced support cost of the API for Banno/Jack Henry.
Decision Outcome
Chosen option: Deprecate API Version, then Drop Support 12 Months Thereafter.
This provides a balance between the need for FIs to have predictable, schedulable changes with the need for Banno/Jack Henry to keep API support costs at a manageable level.
Note: This policy may be impacted by events such as security-related situations where an API might need to be deprecated sooner than expected to ensure the safety of the system or user data. Special care should be taken to avoid such emergency situations. If such a situation should arise, we must take special responsibility to carefully communicate the impact to developers.
Note: This policy may be overridden by deprecation timeframes written into contracts. Special care should be taken to avoid this type of unusual situation.
Considered Options
- Deprecate API Version, then Drop Support 12 Months Thereafter
- Maintain API Versions in Perpetuity
- Drop Support Without Warning
Pros and Cons of the Options
Deprecate API Version, then Drop Support 12 Months Thereafter
- Good, because this provides a warning to consumers of the API that changes are coming.
- Good, because this provides adequate time for consumers of the API to schedule software changes to upgrade to a newer version of the API.
- Good, because it reduces API support costs by defining a timeframe for retiring a particular version of the API.
- Bad, because it means that consumers of the API will eventually need to spend time and effort upgrading to a newer version of the API if they want to maintain functionality.
Maintain API Versions in Perpetuity
- Good, because consumers of the API don’t need to spend time and effort to maintain functionality after their initial investment integrating with the API.
- Bad, because this increases the cost of supporting the API since different versions would be supported in perpetuity.
- Bad, because it may not be technically feasible to support a particular version of the API if our system architecture changes.
Drop Support Without Warning
- Good, because this doesn’t require any effort on our part with regard to planning or communication.
- Bad, because it means that consumers of the API cannot rely upon our API existing over some given timeframe (thus hurting our reputation as a company).
- Bad, because it means that consumers of the API will eventually need to spend time and effort upgrading to a newer version of the API without any ability to budget and plan changes.
- Bad, because this would likely spur consumers of the API to seek out alternatives on the market.