HTTP API Versioning and Need to Introduce Breaking Changes to All Supported Versions

Question

I am developing an HTTP application and deploying this by versioning it against the semantic versioning patterns/techniques/whatever they are. In order not to break existing clients and allow the releases to be flexible, there are several rules for the releases:

• At the same time, it supports two major versions. E.g. 2.3.4 and 3.4.5 can be both supported at the same time but there will be no 2.3.4, 3.4.5, 4.5.6 support for instance.
• It's possible to apply an hot-fix to supported lower version of the HTTP application. E.g, I have two versions of the HTTP application running: 2.3.4 and 3.4.5. I will apply an hot-fix on 2.3.4 release and bump its version to 2.3.5.

This scenario mostly covers all of my needs except for where I need to apply a change to both versions at the same time and that change introduces a breaking change. For example, consider the following scenario:

Version 2.3.4 and 3.4.5 of the application are running. We discovered a security bug and fixing that bug will introduce a breaking change to two of deployed versions. In ideal scenario, I would be version the new release as 4.0.0 and retire the 2.3.4 release. So, 4.0.0 and 3.4.5 will be the supported versions but in this case, 3.4.5 needs to be retired as well as it has security hole.

How would you cover this case or how are you handling it today if you have a similar application and deployment structure? We haven't come across to a scenario like this yet but I really don't want to continue my life with a question mark like this :)

Update:

Why are you originally supporting two different builds?

Several reasons:

1. This HTTP service backs more than one client (let's say thousands). So, it's not possible to update them simultaneously. Classic reason why you want to version your stuff.

2. Let's assume that only consumer of this HTTP service is me. Even with that, it's not possible for me to update my clients and the HTTP application simultaneously. So, I again need versioning. If this was the case, the above scenario would be less of a problem as I am controlling all the clients.

Answer 1

I think in order to answer this question, you need to ask yourself another more important question...

Why are you originally supporting two different builds?

Most likely the answer to that would be because you have customers that have a different tempo at introducing newer major versions, which makes complete sense. So a customer is on 2.3.4 and haven't yet migrated to 3.4.5 because of operations, testing, etc. Whatever the reason, they are slower to adopt. Perhaps this customer implements every other major release.

But in the case of your hotfix causes the absolutely need for a breaking change to both current versions (provided that breaking change is a must). In this case, it would only make sense to increment your major of the build, and have a single build going forward until a secondary major release becomes in support (to then continue following your model of two supported builds for supportability).

The reason I say this is because the benefit of supporting an older major release for customers is no longer there, as you're forcing them to adopt breaking changes in a newer major version.

So in my opinion, this would be a good reason to have a point of convergence to a single supported build until your next natural progression of another major release comes about, in which case you would have your two supported builds again.

After the breaking changes, you'd have version 4.0.0 as the only supported build. And then you would eventually have your 5.x.x build, in which case you would now be supporting both 4.x.x and 5.x.x.