{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["partial"]},"type":"markdown"},"seo":{"title":"API Versioning and Change Communication","description":"What the major version and the x-build-version each mean, how CDQ surfaces the build version, and how the per-API changelog tells you whether a change affects you."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"api-versioning-and-change-communication","__idx":0},"children":["API Versioning and Change Communication"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every CDQ API carries two version numbers and a changelog that together tell you whether a specification has changed and whether the change affects you. The major version marks the compatibility contract, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-build-version"]}," identifies the exact published build, and the per-API changelog explains what moved between builds."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["OpenAPI is the supported machine-readable format for CDQ APIs, so these signals live inside the specification itself. You do not need to keep your own historical archive of specifications to know what changed: the build version tells you whether the document differs from the one you last saw, and the changelog explains the difference in plain language."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["In this article, you will understand:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["What the major ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-build-version"]}," each mean, and how they differ"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How CDQ surfaces the build version inside the specification and in the portal"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How the per-API changelog answers whether a change affects you"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-is-the-build-version","__idx":2},"children":["What is the build version?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A CDQ specification carries two independent version numbers in its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info"]}," block, and they answer different questions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["major version"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.version"]},") is the compatibility contract. It appears in the endpoint URI path (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v2/"]},") and changes only when CDQ releases a new, parallel major version. You pin your integration to a major version, and it stays stable for a long time. The semantic-versioning and end-of-life policy behind it is described in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/_public/developer-guidelines#versioning"},"children":["Developer Guidelines"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["build version"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.x-build-version"]},") identifies the exact published build of that major version. It moves on every republish, including backward-compatible changes that keep the same major version. It answers a narrower question: is this the same document I saw last time?"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"info:\n  title: Business Partner API\n  version: '3'\n  x-build-version: v3-2.45.677\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The build version follows a fixed shape, so its parts are unambiguous:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"v{SPEC_VERSION}-{BUILD_MAJOR}.{BUILD_MINOR}.{BUILD_PATCH}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v3-2.45.677"]}," means major version 3, build 2.45.677. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SPEC_VERSION"]}," segment always matches ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.version"]},", so the build version carries the major version with it."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-the-build-version-is-surfaced","__idx":3},"children":["How the build version is surfaced"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["CDQ makes the build version visible in two places, so both machines and people can read it:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Inside the specification"]},", as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.x-build-version"]},". Because it travels in the OpenAPI document, any system that imports the spec also receives the build version without a separate lookup."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["In the portal"]},", as a bold ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Build version:"]}," line at the top of the API description, so a reader can see which build they are looking at."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because the value identifies the published document, comparing the build version of a current specification against the one seen earlier is enough to tell whether anything changed. Equal values mean the same document; a different value means a new build to review. There is no need to compare the whole file."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-per-api-changelog","__idx":4},"children":["The per-API changelog"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The build version tells you ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["that"]}," something changed. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/changelog"},"children":["changelog"]}," tells you ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["what"]}," changed and whether you need to act. Each API has its own changelog view, which you can open directly or filter by product."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every entry is written to answer three questions:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What changed?"]}," The entry names the new build version and lists the most important changes, breaking changes first."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Does it affect me?"]}," The entry states whether the changes are backward-compatible or include breaking changes, and which product and major version they apply to."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What do I need to do?"]}," A backward-compatible build needs no action; a build with breaking changes should be reviewed before you move your integration to a new major version."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A backward-compatible build keeps the same major version, so an existing integration continues to work. A breaking change is released as a new major version, communicated in advance, with the retirement schedule described in the Developer Guidelines."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-this-means-for-consuming-specifications","__idx":5},"children":["What this means for consuming specifications"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a system that imports CDQ specifications, for example into an API Management Gateway, the mechanism replaces guesswork with two plain signals. The build version in the specification says whether the document is new; the changelog says whether the change is safe to adopt or needs review first."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Neither signal requires storing past specifications. The last build version seen is the only state worth remembering, and the changelog keeps the history on CDQ's side."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary","__idx":6},"children":["Summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["CDQ communicates API change through three layers that work together: the major version is the stable compatibility contract, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-build-version"]}," is the build identifier that moves on every republish, and the per-API changelog explains what changed and whether it affects you. All three are carried by the OpenAPI specification and the portal, so consuming them needs no separate archive of your own."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the versioning and end-of-life policy, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/_public/developer-guidelines#versioning"},"children":["Developer Guidelines"]},". For the change history itself, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/changelog"},"children":["Changelog"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-resources","__idx":7},"children":["Related Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/_public/developer-guidelines#versioning"},"children":["Developer Guidelines: Versioning"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/changelog"},"children":["Changelog"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"your-opinion-matters","__idx":8},"children":["Your opinion matters!"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!"]}]},"headings":[{"value":"API Versioning and Change Communication","id":"api-versioning-and-change-communication","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"What is the build version?","id":"what-is-the-build-version","depth":2},{"value":"How the build version is surfaced","id":"how-the-build-version-is-surfaced","depth":2},{"value":"The per-API changelog","id":"the-per-api-changelog","depth":2},{"value":"What this means for consuming specifications","id":"what-this-means-for-consuming-specifications","depth":2},{"value":"Summary","id":"summary","depth":2},{"value":"Related Resources","id":"related-resources","depth":2},{"value":"Your opinion matters!","id":"your-opinion-matters","depth":2}],"frontmatter":{"seo":{"title":"API Versioning and Change Communication","description":"What the major version and the x-build-version each mean, how CDQ surfaces the build version, and how the per-API changelog tells you whether a change affects you."},"toc":{"enable":true},"cdqContentMetadata":{"product":"CDQ Developer Portal","lastUpdate":"2026-11-06T00:00:00.000Z","author":"Łukasz Michta"}},"lastModified":"2026-11-06T12:18:29.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/documentation/_public/articles/api-versioning-and-change-communication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}