[GH-ISSUE #434] Implicit 'upgraded' support for unsupported API version #4563

New Issue

GiteaMirror · 2026-06-13T12:48:01-05:00

GiteaMirror commented

2026-06-13 12:48:01 -05:00

Originally created by @hoylemd on GitHub (Mar 15, 2018).
Original GitHub issue: https://github.com/semver/semver/issues/434

Hey folks,

The project I'm working on is a REST API. We want to use semantic versioning, but we don't want to support every published version in perpetuity, because that would necessitate either 'hard-coding' support for multiple versions into the application or maintaining many deploys. This becomes even more relevant for patch versions, because we definitely don't want clients using, say, version 1.2.1 if an important bug fix was added in 1.2.2.

A possible solution we're considering is to have deprecated minor and patch versions implicitly upgraded to the closest supported version (requests for deprecated major versions would definitely error out).

An example to illustrate with patch and minor versions:

Versions 1.0.0, 1.0.1, 1.1.0, 1.1.2, 1.1.3, and 1.2.0 have been published, but 1.0.0, 1.1.0, 1.1.2 and 1.1.3 have been deprecated (so 1.0.1, and 1.2.0 are still supported).

If a request specifies version 1.0.0, we would transparently 'upgrade' the request to version 1.0.1. A request for 1.1.2 would be treated as a request for 1.2.0 and therefore may return a response with fields added in version 1.2.0. We're assuming that consumers of the API wouldn't break upon receiving extra data, since we're using JSON as a content type.

I'm wondering is this an acceptable implementation of semver? Are there any significant drawbacks I've overlooked?

We're also considering omitting the patch part of the version specifier in the version header of requests. So you'd always ask for version x.y - patch version is invisible to consumers. Any comments on that idea would also be useful.

Thanks for your time!

Originally created by @hoylemd on GitHub (Mar 15, 2018). Original GitHub issue: https://github.com/semver/semver/issues/434 Hey folks, The project I'm working on is a REST API. We want to use semantic versioning, but we don't want to support *every* published version in perpetuity, because that would necessitate either 'hard-coding' support for multiple versions into the application or maintaining many deploys. This becomes even more relevant for patch versions, because we definitely don't want clients using, say, version `1.2.1` if an important bug fix was added in `1.2.2`. A possible solution we're considering is to have deprecated minor and patch versions implicitly upgraded to the closest supported version (requests for deprecated major versions would definitely error out). An example to illustrate with patch and minor versions: Versions `1.0.0`, `1.0.1`, `1.1.0`, `1.1.2`, `1.1.3`, and `1.2.0` have been published, but `1.0.0`, `1.1.0`, `1.1.2` and `1.1.3` have been deprecated (so `1.0.1`, and `1.2.0` are still supported). If a request specifies version `1.0.0`, we would transparently 'upgrade' the request to version `1.0.1`. A request for `1.1.2` would be treated as a request for `1.2.0` and therefore may return a response with fields added in version `1.2.0`. We're assuming that consumers of the API wouldn't break upon receiving *extra* data, since we're using JSON as a content type. I'm wondering is this an acceptable implementation of semver? Are there any significant drawbacks I've overlooked? We're also considering omitting the patch part of the version specifier in the version header of requests. So you'd always ask for version `x.y` - patch version is invisible to consumers. Any comments on that idea would also be useful. Thanks for your time!

GiteaMirror closed this issue

2026-06-13 12:48:04 -05:00

GiteaMirror commented

2026-06-13 12:48:08 -05:00

@jwdonahue commented on GitHub (Mar 25, 2018):

Let me see if I understand this. You have a REST API that allows clients to specify which version of the API they wish to communicate with? You intend to respond to requests targeted at a deprecated version of the API with responses from a higher, but hopefully compatible version? You want to know if this an acceptable implementation of SemVer?

On that later question, SemVer does not say anything at all about how you implement such behaviors. It only defines the semantics and syntax of the version string and is mute on your upgrade policies. Point us to your parsing code and a complete description of your development practices and in time, we might be able to pass judgement on the matter, but it is unlikely anyone can do it justice for free. As it stands, what you are asking seems out of scope for SemVer. SemVer does not define how your tool should specify/handle version ranges, and what you describe sounds a lot like implementing an implicit version range of some sort.

Normally, I think a REST API should fail a request it cannot honor. A well designed API would suggest a substitute version, version list or range of acceptable requests and leave it up to the client developers, exactly what their policies should be at that point. In fact, you might want to also consider baking a version range specification into the client request so-as to save a round trip when an exact match is not available. In other words, ranges should be explicit, not implicit, give your clients control and sufficient information to make the necessary choices. The version of your REST API isn't the only factor here, the versions of the client implementation combines with the server versions in sometimes unpredictable ways. At some point, you are going to have some 1.x.x and 2.x.x services available. Some clients might skip supporting 1.9.999 and jump to 2.0.1, but they prefer to use the well-worn 1.x.x API, they may find at some point that you've deprecated all 1.x.x except for 1.9.999. Since 2.x.x is a breaking change over 1.x.x, it is ill-advised to implicitly force the upgrade, but a client could announce support for a range that includes 2.x.x and you just might be able to satisfy that request. As the client dev's gain experience with the 2.x.x version of your API, they just might begin restricting their range to 2.x.x.

Hope that helps. Let me know if you have any further questions.

@jwdonahue commented on GitHub (Mar 25, 2018): Let me see if I understand this. You have a REST API that allows clients to specify which version of the API they wish to communicate with? You intend to respond to requests targeted at a deprecated version of the API with responses from a higher, but hopefully compatible version? You want to know if this an acceptable implementation of SemVer? On that later question, SemVer does not say anything at all about how you implement such behaviors. It only defines the semantics and syntax of the version string and is mute on your upgrade policies. Point us to your parsing code and a complete description of your development practices and in time, we might be able to pass judgement on the matter, but it is unlikely anyone can do it justice for free. As it stands, what you are asking seems out of scope for SemVer. SemVer does not define how your tool should specify/handle version ranges, and what you describe sounds a lot like implementing an implicit version range of some sort. Normally, I think a REST API should fail a request it cannot honor. A well designed API would suggest a substitute version, version list or range of acceptable requests and leave it up to the client developers, exactly what _their_ policies should be at that point. In fact, you might want to also consider baking a version range specification into the client request so-as to save a round trip when an exact match is not available. In other words, ranges should be explicit, not implicit, give your clients control and sufficient information to make the necessary choices. The version of your REST API isn't the only factor here, the versions of the client implementation combines with the server versions in sometimes unpredictable ways. At some point, you are going to have some 1.x.x and 2.x.x services available. Some clients might skip supporting 1.9.999 and jump to 2.0.1, but they prefer to use the well-worn 1.x.x API, they may find at some point that you've deprecated all 1.x.x except for 1.9.999. Since 2.x.x is a breaking change over 1.x.x, it is ill-advised to implicitly force the upgrade, but a client could announce support for a range that includes 2.x.x and you just might be able to satisfy that request. As the client dev's gain experience with the 2.x.x version of your API, they just might begin restricting their range to 2.x.x. Hope that helps. Let me know if you have any further questions.

GiteaMirror commented

2026-06-13 12:48:09 -05:00

@jwdonahue commented on GitHub (Jun 26, 2018):

@hoylemd

Unless you have further questions, please close this issue.

@jwdonahue commented on GitHub (Jun 26, 2018): @hoylemd Unless you have further questions, please close this issue.

GiteaMirror commented

2026-06-13 12:48:10 -05:00

@hoylemd commented on GitHub (Jun 28, 2018):

Whoops! I meant to close it ages ago, but it must have slipped my mind. Thanks for the reminder @jwdonahue

@hoylemd commented on GitHub (Jun 28, 2018): Whoops! I meant to close it ages ago, but it must have slipped my mind. Thanks for the reminder @jwdonahue

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#4563