I version my APIs (of various types: REST, Java, etc.) according to the rules of semantic versioning (for REST API specifying the version in the OAS in the version
field of the Info Object; for Java API, this is the version
attribute of the corresponding artifact - the part of groupId, artifactId, version
).
Currently, I want to introduce the practice of marking some API elements as experimental (for REST API, use a custom extension; for Java API, use a custom annotation).
Now, I can't understand how I should proceed with the API version in case of deleting the experimental element?
Case:
5.1.0
.6.0.0
, 5.1.1
or something else?Arguably this is an opinion-based question but I will try to give my take on the subject.
If it is possible I would heavily suggest "hiding" experimental features behind some flag/header (like enableExperimentalFeatures
) so user will need to explicitly "consent" on using those and verifies that all risks are understood (hence no compatibility guarantees are given). This will allow you to manipulate only the minor/patch versions and not to "litter" the version pool with major ones which do not actually have any major changes for stable API.
Alternatively you can ship two version, one with experimental
suffix following the pre-release versioning handling suggested by the SemVer (i.e. you will ship X.Y.Z
and X.Y.Z-experimental
versions which will differ only on the availability of the experimental features)