mirror of
https://github.com/semver/semver.git
synced 2026-07-11 06:53:03 -05:00
Implicit 'upgraded' support for unsupported API version #319
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#319
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @hoylemd on GitHub (Mar 15, 2018).
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.1if an important bug fix was added in1.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, and1.2.0have been published, but1.0.0,1.1.0,1.1.2and1.1.3have been deprecated (so1.0.1, and1.2.0are still supported).If a request specifies version
1.0.0, we would transparently 'upgrade' the request to version1.0.1. A request for1.1.2would be treated as a request for1.2.0and therefore may return a response with fields added in version1.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!
@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 (Jun 26, 2018):
@hoylemd
Unless you have further questions, please close this issue.
@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