0

In OpenAPI, is there a convention for denoting that your API is not stable yet?

In semantic versioning, the v0.x.x version number is usually used to indicate that the project is not stable yet. OpenAPI seems to be using semantic versioning, but the spec did not make any explicit statements about this. In a young project, is it considered good practice to have a v0 route (e.g. /api/v0/...) where you're free to make breaking changes without bumping major versions?

Related is the proposal to add an experimental marker: https://github.com/OAI/OpenAPI-Specification/issues/432. Though this doesn't help indicate that your project as a whole has yet to reach stability/maturity.

Improve this question
2
  • Do projects ever reach stability and maturity? Gone are the days when you build something and make backwards compatible changes for 20 years.
    – Greg Burghardt
    Commented Oct 21 at 18:34
  • @GregBurghardt you may choose a versioning standard to indicate known instability, even after the first release is out - for example in a MAJOR.MINOR.BUILD scheme you may use odd MINOR numbers to indicate a "dev" or early access version - hence when things firm up you bump the MINOR version to the next even number.
    – DavidT
    Commented Oct 22 at 15:43

1 Answer 1

Reset to default
1

It doesn't look like OpenAPI makes any comment on how you specify the version of your API document. You can use any string in the info object.

Semantic versioning allows for a "pre-release" identifier after the version. ie 1.2.3-beta

<valid semver> ::= <version core>
                 | <version core> "-" <pre-release>
                 | <version core> "+" <build>
                 | <version core> "-" <pre-release> "+" <build>

On further checking, OpenAPI does recommend semver in its "how to version" guidelines

https://openapispec.com/docs/how/how-does-openapi-handle-api-versioning/#3-version-increment-guidelines

My preference is for Header versioning as it takes the version away from the rest of the API specification and keeps the routing firmly in your control.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.