javaopenapiapi-designsemantic-versioning

Semantic versioning and the experimental API element


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:

  1. Adding an experimental element to the API version 5.1.0.
  2. I am removing an experimental element from the API. What version of the API should I give: 6.0.0, 5.1.1 or something else?

Solution

  • 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)