DevOps – Versioning

DateVersionChanges
2021-11-21v1.0.0
2025-10-17v1.1.0Moved from Confluence

1. Applications / Systems / Libraries

The word Application will be used to also refer to systems and libraries.

1.1 All applications MUST be versioned according to Semantic Versioning 2.0.

1.2 First development version of an application SHOULD be v0.1.0.

1.3 First production version of an application SHOULD be v1.0.0.

1.4 Application version MUST be incremented when production environment is updated.

1.5 Pre-release version number MAY be incremented when it’s helpful. Example, for versioning test releases.

2. HTTP APIs

Same rules applies to RPC, REST and GraphQL APIs.

2.1 First production version of an HTTP API MUST be v1.

2.2 API version SHOULD be specified as the first part of the query. Example, /v1/users

2.3 API version MUST be incremented when introducing breaking changes.

  • A change is considered breaking if it requires an API client to be updated.
  • A change is considered safe if clients will continue to work with no change in behaviour.

2.4 HTTP APIs SHOULD communicate latest API version in HTTP header X-API-Last-Version. 

2.5 HTTP APIs SHOULD NOT duplicate functionality to avoid incrementing the API version. Example, you should not create a /v1/users2 to avoid version increment of the API.

2.6 Versioning HTTP API’s MAY be omitted if the same team is authoring the only client.

3. Deprecating APIs

3.1 Old API versions MUST be supported until they’ve been officially deprecated.

3.2 All clients MUST be notified with an upgrade plan in good time before version deprecation.

3.3 API versions that are up for deprecation MUST communicate deprecation date in HTTP header X-API-Deprecation-Date in ISO 8601 format. Example, 2022-01-01.

3.4 Deprecated APIs MUST stop serving content and respond with HTTP status 404 Not Found.

3.5 API deprecation MAY be omitted if the same team is authoring the only client. Working with iOS and Android apps, API deprecation could still be a useful tool for handling old installations of the app.