Werk #18004: Introduction of versioning framework for REST API
| Component | REST API | ||
| Title | Introduction of versioning framework for REST API | ||
| Date | Jun 10, 2025 | ||
| Level | Trivial Change | ||
| Class | New Feature | ||
| Compatibility | Compatible - no manual interaction needed | ||
| Checkmk versions & editions |
|
This werk introduces a versioning framework to the REST API, changing how API modifications are introduced and aiming to provide better stability for automation scripts and integrations. This werk only concerns the versioning framework itself and a dedicated werk will be published for each major version (including the existing v1).
Background
Prior to this werk, the REST API was fully tied to the underlying Checkmk version, meaning that scripts using the REST API could require adjustment whenever Checkmk was upgraded. The API could be changed in incompatible ways, which was communicated through Werks but provided no advance warning.
Versioning Framework
Semantic Versioning Approach
We introduce a Semantic Versioning (SemVer) approach for the new versioning framework of the API. However, instead of following the traditional x.x.x SemVer format, we use a simplified major version format (e.g., "1" instead of "1.0.0"). This decision was made since minor and patch versions represent compatible changes.
The API versioning applies to the entire API rather than to individual endpoint families or endpoints.
Versioning Policies
Within Checkmk Major Versions
All published REST API versions will be continuously supported within a Checkmk major version. This guarantees that existing API scripts continue to work without modification during routine Checkmk patch updates.
Once a new Checkmk major version is released, the previous Checkmk stable version will only receive API compatible fixes, which should ensure version stability and prevent unexpected breaking changes.
Between Checkmk major versions, at least the latest REST API major version will be supported.
Unstable Version for Development
Experimental Features
A dedicated "unstable" API version is introduced for experimental features and backports. This version serves as a testing ground for new features before they are promoted to stable versions. The unstable version also allows backports to be introduced to older Checkmk major versions without breaking the API versioning sequence, preventing REST API versions from falling out of sync across different Checkmk releases.
Unstable version content is unique to each Checkmk major version.
No Stability Guarantees
Unstable endpoints may be removed or modified at any time without prior notice. Users should only use this version for testing and development purposes.
Important Limitations
Internal Checkmk Dependencies
Internal Checkmk fixes may occasionally override versioning rules when necessary. The versioning framework applies at the API level and not at the internal Checkmk level, meaning that core system requirements may occasionally necessitate breaking changes.
Any such breaking changes will be communicated through the Werks system with all affected API versions clearly listed and an accompanying resolution guide.