SaFi Bank Space : REST API versioning - major version upgrades

Created by Juraj Macháč on Aug 18, 2022

Status

IN PROGRESS

Impact

MEDIUM

Driver

Juraj Macháč (Unlicensed)

Approver

Contributors

Informed

Due date

Resources

(blue star) Relevant data

(blue star) Background

The microservices expose REST endpoints to be called by other microservices. The squads provide the APIs to other squads as a service, and should avoid imposing breaking changes on their consumers. Hence the need for API versioning of the microservices within our ecosystem.

This document does not discuss what is a breaking change, but how to manage the major version upgrades of the REST API of our services.

Please consider the fact that we are in control in most of the consumers of all of the APIs. Hence, it should be in our collective best intentions to prioritize upgrading to the latest API of the provider service to allow it to evolve and remove tech debt (old APIs). The exceptions of control are:

  • 3rd party integrations with ingress connections

  • Mobile app - the customers update their Apps at will, so we need to consider older versions running. However, there is some control over it as we should have mechanisms to enforce an update.

(blue star) Options considered

Versions in controllers within services

One API per service code with different service versions deployed

Description

The microservice will contain all API versions packaged within the application. Different versions of API will be separated by controllers. All deployed pods are the same.

The running microservice code always contains only a single API version. Upgrading the API version is done by creating a new pods which host only the new API, while keeping the services with the former API running and untouched.

Pros and cons

(minus) Service becomes larger. Duplicated component tests per API version

(plus) there is (almost) always just a single version of the service deployed. Having such holistic view in code on all the API versions deployed implies simpler reasoning about not breaking the system (e.g. with DB migration) when making changes to the codebase.

(plus) component tests always run also for the old API versions whenever any change occurs in the service

(plus) changes and fixes can be applied to older versions of API if necessary.

(plus) possible to apply static analysis on the code to figure out for each service what are all the API versions it provides and consumes

(plus) less clutter in the service code

(plus) the deployed applications are smaller

(minus) potentially more management for individual service scaling per API version. For all the previous versions of a service which are still supported, there need to be sufficient number of instances available.

(minus) more difficult to reason about changes in a common dependency such as DB, as it is not clear from the code what do all the consumers look like. Testing how the old APIs behave on such migration is virtually impossible without integration test and applying the migration in the test environment.

(minus) difficult change management for older running versions as the changes in the code need to be done against old codebase (or no change management?)

Estimated cost

MEDIUM

MEDIUM

(blue star) Action items

(blue star) Outcome