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.

Kyle Richards
  • 123

1 Answers1

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.

Ewan
  • 83,178