Api versioning💡
Sometimes it is necessary to make backwards incompatible changes to an API. This may lead to breakage of dependent services.
The 3DI API versioning policy limits breaking changes by introducing "stable" and "beta" stability levels, each with a different contract:
- The "stable" version
V3does not get backwards incompatible changes. It is long-lived. - The "beta" version
v3-betamay get backwards incompatible changes, but they must be announced beforehand. Features in "beta" may graduate to "stable".
The different versions are all listed in 1 API root.
If necessary, a complete version (stable, beta) may be deprecated (removed). This must be announced at least 180 days beforehand.
The "beta" is a superset of "stable". It is allowed to put redirects beta -> stable and as such hide them in the API endpoint listing and in the OpenAPI specification.
This policy is based on the Google versioning policy: https://cloud.google.com/apis/design/versioning.
Threedi and threedicore versioning💡
The following two version numbers describe the 3Di framwork version and the threedicore (calccore) version.
- The
threedi_versionis increased when the 3Di framework is updated. - The
threedicore_versionis increased when the calcore is updated.
An update can contain bugfixes and/or new features.
Note: These version numbers can be found in /swagger or v3-beta/status/current-version/