📅 API Versioning & Compatibility

Basic knowledge of HTTP requests (setting Accept and Content-Type headers)
Access to the latest YAML files for each module (see 📚 API Documentation & YAML Files for download)

ℹ️ Note:
Incorrect or missing version information in headers often results in 415 Unsupported Media Type errors.

Versions are module-specific – each API module (e.g., KPI, Taskboard) has its own version.
The version is not included in the URL but is specified in the Media Type of the HTTP headers (Accept and, if applicable, Content-Type).
Minor changes (e.g., optional fields) are generally backward compatible.
Major changes (e.g., renamed fields, changed mandatory fields, modified structures) can cause breaking changes.

Module	Version	Media Type (Accept / Content-Type)
KPI API	v2.0	`application/vs.v2.0+json`
List Editor	v2.0	`application/vs.v2.0+json`
Taskboard	v1.0.0	`application/json` (unless otherwise specified)
Deviation	v1.0.0	`application/json` (module-specific exceptions, see YAML)
Countermeasures	v1.0.0	`application/json` (module-specific exceptions, see YAML)
Processboard	v1.0.0	`application/vs.pb.v1.0.0+json`

✨ Tip: Check the consumes/produces section in the YAML file to confirm the correct media type.

Older versions remain available for a limited period after a new version is released (duration depends on module and release plan).
When a new major version is released, it will be announced in the Release Notes and the Support Newsletter.

Examples of Breaking Changes:

✅ Recommendation: Regularly check integrations against the YAML specification.

⚠️ Warning: For deprecated versions, access may be disabled without further notice once the grace period ends.

Always keep Accept and Content-Type headers consistent with the module version.
Use YAML files as a reference – especially before updates.
Test new versions in a staging/test environment before going live.
Document all API versions used in your systems.
Schedule regular review cycles to detect changes early.

How can I find the currently valid version of a module?
→ In the module’s YAML file under info.version and in the produces/consumes section.

Do I need to specify the version in the URL path?
→ No, the version is set exclusively in the Media Type header.

What happens if I use the wrong media type?
→ The API responds with 415 Unsupported Media Type.

Will I be warned before an old version is shut down?
→ Yes, via Release Notes and Support communications. The lead time varies by module.

This article explains how ValueStreamer manages API versions, how to specify them in requests, and how to ensure integrations remain compatible with future versions. It includes an overview of all current module versions, media types, and best practices.