From 25068e61f95a3923ffbf288c08d0f8229cb21af6 Mon Sep 17 00:00:00 2001 From: Nicola Puppa Date: Tue, 24 Mar 2026 11:59:31 +0100 Subject: [PATCH 1/2] docs(apis): add client and API compatibility section (#41938) - Add "Client and API compatibility" section to public-api.md with forward/backward compatibility table for clients, SDKs, CPT, and REST APIs - Add compatibility note in 8.9 announcements (APIs & tools section) - Add compatibility summary with link in working-with-apis-tools.md --- docs/apis-tools/working-with-apis-tools.md | 6 +++ .../890/890-announcements.md | 4 ++ docs/reference/public-api.md | 45 +++++++++++++++++++ 3 files changed, 55 insertions(+) diff --git a/docs/apis-tools/working-with-apis-tools.md b/docs/apis-tools/working-with-apis-tools.md index 8339c742f2d..c96ca4a78db 100644 --- a/docs/apis-tools/working-with-apis-tools.md +++ b/docs/apis-tools/working-with-apis-tools.md @@ -58,6 +58,12 @@ Use Camunda Process Test to test your process definitions and automations with a

[Camunda Process Test](/apis-tools/testing/getting-started.md)

+## Client and API compatibility + +Camunda clients and SDKs are **forward-compatible** and **backward-compatible** with the Orchestration Cluster, meaning you can upgrade the cluster and clients independently. The Orchestration Cluster REST API is backward-compatible, ensuring no breaking changes to existing endpoints across versions. + +

[Learn more about compatibility guarantees](/reference/public-api.md#client-and-api-compatibility)

+ ## Upgrade to Camunda 8.9 If you are migrating from Camunda 7 or from v1 component REST APIs, see the migration guide for guidance. diff --git a/docs/reference/announcements-release-notes/890/890-announcements.md b/docs/reference/announcements-release-notes/890/890-announcements.md index 3c1f6fa3d4b..e63d9b2f26d 100644 --- a/docs/reference/announcements-release-notes/890/890-announcements.md +++ b/docs/reference/announcements-release-notes/890/890-announcements.md @@ -148,6 +148,10 @@ Camunda 8.9 now supports Elasticsearch 9.2+ and OpenSearch 3.4+, allowing you to :::info 8.9 APIs & Tools migration guide Migrate your API integrations, SDKs, and generated clients to Camunda 8.9 using the [8.9 APIs & Tools migration guide](/apis-tools/migration-manuals/migrate-to-89.md). ::: + +:::tip Client and API compatibility +Camunda clients (Java client, Spring SDK, Node.js SDK) and Camunda Process Test are **forward-compatible** and **backward-compatible** with the Orchestration Cluster. This means you can upgrade the cluster and clients independently — for example, running a client on 8.8 against a cluster on 8.9, or upgrading the client to 8.9 without code changes. See [Client and API compatibility](/reference/public-api.md#client-and-api-compatibility) for details. +:::
diff --git a/docs/reference/public-api.md b/docs/reference/public-api.md index eb34b06147f..829a9d19a5b 100644 --- a/docs/reference/public-api.md +++ b/docs/reference/public-api.md @@ -69,3 +69,48 @@ Though not covered by the public API contract, we aim to provide a consistent ex - Avoiding breaking changes to configuration, endpoints, or backup-related features within the same minor release range. This balance allows continuous improvement to tools like Web Modeler and Console, while preserving stability for orchestration logic. + +## Client and API compatibility + +Public API components follow strict compatibility guarantees so you can upgrade clients and clusters independently. + +| Component | Forward-compatible | Backward-compatible | +| ----------------------------------------------------------------------------------------------------------------------- | :----------------: | :-----------------: | +| [Camunda Java client](/apis-tools/java-client/getting-started.md) | ✅ | ✅ | +| [Spring SDK](/apis-tools/camunda-spring-boot-starter/getting-started.md) | ✅ | ✅ | +| [Node.js SDK](https://github.com/camunda/camunda-nodejs-sdk) | ✅ | ✅ | +| [Camunda Process Test](/apis-tools/testing/getting-started.md) | ✅ | ✅ | +| [Orchestration Cluster REST API](/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview.md) | — | ✅ | + +- **Forward-compatible** means a client can work with a _newer_ version of the Orchestration Cluster than the client version. +- **Backward-compatible** means a client can be upgraded to a _newer_ version without requiring changes to your application code. + +### Clients and SDKs + +The Camunda Java client, Spring SDK, Node.js SDK, and Camunda Process Test (CPT) are both **forward-compatible** and **backward-compatible** with the Orchestration Cluster. + +**Forward compatibility** means your application can use an older client version and still work correctly against a newer cluster. For example, an application using Camunda Java client **8.8.3** works against an Orchestration Cluster running **8.9.1**. This allows you to upgrade the Orchestration Cluster first without immediately updating your client libraries. + +**Backward compatibility** means that when you upgrade the client or SDK version in your application, no code changes are required. New minor and patch versions of the clients do not introduce breaking changes. For example, upgrading the Spring SDK dependency from **8.8.x** to **8.9.x** does not require changes to your application code. + +### Camunda Process Test (CPT) + +CPT is both forward-compatible and backward-compatible with the Orchestration Cluster and Connectors runtime: + +- **Forward-compatible**: You can change the version of the Orchestration Cluster/Connectors bundle in your tests to a newer version without any changes. +- **Backward-compatible**: Upgrading the CPT dependency version does not require changes to your existing tests. + +### REST APIs + +The [Orchestration Cluster REST API](/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview.md) is **backward-compatible**. No breaking changes are introduced to existing endpoints in newer versions of the Orchestration Cluster. For example, if you build a custom client implementation against the **8.8** REST APIs, it continues to work against a newer Orchestration Cluster version such as **8.9**. + +:::note +Because REST API endpoints are part of the Orchestration Cluster itself, forward compatibility does not apply — your cluster version determines which endpoints are available. +::: + +### Recommended upgrade order + +When upgrading across minor versions, the recommended approach is: + +1. **Upgrade the Orchestration Cluster first.** Forward compatibility of clients ensures your existing applications continue to work. +2. **Upgrade your client libraries.** Backward compatibility of clients ensures no code changes are needed. From dc5e21829e8ab26e2bd30814f8fa7f9982372ab9 Mon Sep 17 00:00:00 2001 From: mesellings Date: Thu, 2 Apr 2026 14:54:53 +0100 Subject: [PATCH 2/2] docs(apis): TW edits --- docs/apis-tools/working-with-apis-tools.md | 12 +++++------ .../890/890-announcements.md | 2 +- docs/reference/public-api.md | 20 +++++++++---------- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/apis-tools/working-with-apis-tools.md b/docs/apis-tools/working-with-apis-tools.md index c96ca4a78db..eae3b602361 100644 --- a/docs/apis-tools/working-with-apis-tools.md +++ b/docs/apis-tools/working-with-apis-tools.md @@ -52,17 +52,17 @@ Camunda provides the following official clients to simplify API usage and speed In addition to the core Camunda-maintained clients, there are a number of [community-maintained component clients](/apis-tools/community-clients/index.md). ::: -## Testing +## Client and API compatibility -Use Camunda Process Test to test your process definitions and automations with a dedicated testing framework. +Camunda clients and SDKs are **forward-compatible** and **backward-compatible** with the Orchestration Cluster, meaning you can upgrade the cluster and clients independently. The Orchestration Cluster REST API is backward-compatible, ensuring no breaking changes to existing endpoints across versions. -

[Camunda Process Test](/apis-tools/testing/getting-started.md)

+

[Client and API compatibility guarantees](/reference/public-api.md#client-and-api-compatibility)

-## Client and API compatibility +## Testing -Camunda clients and SDKs are **forward-compatible** and **backward-compatible** with the Orchestration Cluster, meaning you can upgrade the cluster and clients independently. The Orchestration Cluster REST API is backward-compatible, ensuring no breaking changes to existing endpoints across versions. +Use Camunda Process Test to test your process definitions and automations with a dedicated testing framework. -

[Learn more about compatibility guarantees](/reference/public-api.md#client-and-api-compatibility)

+

[Camunda Process Test](/apis-tools/testing/getting-started.md)

## Upgrade to Camunda 8.9 diff --git a/docs/reference/announcements-release-notes/890/890-announcements.md b/docs/reference/announcements-release-notes/890/890-announcements.md index e63d9b2f26d..1e5a8a87aa6 100644 --- a/docs/reference/announcements-release-notes/890/890-announcements.md +++ b/docs/reference/announcements-release-notes/890/890-announcements.md @@ -150,7 +150,7 @@ Migrate your API integrations, SDKs, and generated clients to Camunda 8.9 using ::: :::tip Client and API compatibility -Camunda clients (Java client, Spring SDK, Node.js SDK) and Camunda Process Test are **forward-compatible** and **backward-compatible** with the Orchestration Cluster. This means you can upgrade the cluster and clients independently — for example, running a client on 8.8 against a cluster on 8.9, or upgrading the client to 8.9 without code changes. See [Client and API compatibility](/reference/public-api.md#client-and-api-compatibility) for details. +Camunda clients (Java client, Spring SDK, Node.js SDK) and Camunda Process Test are **forward-compatible** and **backward-compatible** with the Orchestration Cluster, meaning you can upgrade the cluster and clients independently. For example, you can run a client on 8.8 against a cluster on 8.9, or upgrade the client to 8.9 without code changes. See [Client and API compatibility](/reference/public-api.md#client-and-api-compatibility). :::
diff --git a/docs/reference/public-api.md b/docs/reference/public-api.md index 829a9d19a5b..393b5cd5de9 100644 --- a/docs/reference/public-api.md +++ b/docs/reference/public-api.md @@ -76,22 +76,22 @@ Public API components follow strict compatibility guarantees so you can upgrade | Component | Forward-compatible | Backward-compatible | | ----------------------------------------------------------------------------------------------------------------------- | :----------------: | :-----------------: | -| [Camunda Java client](/apis-tools/java-client/getting-started.md) | ✅ | ✅ | -| [Spring SDK](/apis-tools/camunda-spring-boot-starter/getting-started.md) | ✅ | ✅ | -| [Node.js SDK](https://github.com/camunda/camunda-nodejs-sdk) | ✅ | ✅ | -| [Camunda Process Test](/apis-tools/testing/getting-started.md) | ✅ | ✅ | -| [Orchestration Cluster REST API](/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview.md) | — | ✅ | +| [Camunda Java client](/apis-tools/java-client/getting-started.md) | ✅ Yes | ✅ Yes | +| [Spring SDK](/apis-tools/camunda-spring-boot-starter/getting-started.md) | ✅ Yes | ✅ Yes | +| [Node.js SDK](https://github.com/camunda/camunda-nodejs-sdk) | ✅ Yes | ✅ Yes | +| [Camunda Process Test](/apis-tools/testing/getting-started.md) | ✅ Yes | ✅ Yes | +| [Orchestration Cluster REST API](/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview.md) | — | ✅ Yes | -- **Forward-compatible** means a client can work with a _newer_ version of the Orchestration Cluster than the client version. -- **Backward-compatible** means a client can be upgraded to a _newer_ version without requiring changes to your application code. +- **Forward-compatible**: A client can work with a _newer_ version of the Orchestration Cluster than the client version. +- **Backward-compatible**: A client can be upgraded to a _newer_ version without requiring changes to your application code. ### Clients and SDKs The Camunda Java client, Spring SDK, Node.js SDK, and Camunda Process Test (CPT) are both **forward-compatible** and **backward-compatible** with the Orchestration Cluster. -**Forward compatibility** means your application can use an older client version and still work correctly against a newer cluster. For example, an application using Camunda Java client **8.8.3** works against an Orchestration Cluster running **8.9.1**. This allows you to upgrade the Orchestration Cluster first without immediately updating your client libraries. +- **Forward compatibility**: Your application can use an older client version and still work correctly against a newer cluster. For example, an application using Camunda Java client **8.8.3** works against an Orchestration Cluster running **8.9.1**. This allows you to upgrade the Orchestration Cluster first without immediately updating your client libraries. -**Backward compatibility** means that when you upgrade the client or SDK version in your application, no code changes are required. New minor and patch versions of the clients do not introduce breaking changes. For example, upgrading the Spring SDK dependency from **8.8.x** to **8.9.x** does not require changes to your application code. +- **Backward compatibility**: When you upgrade the client or SDK version in your application, no code changes are required. New minor and patch versions of the clients do not introduce breaking changes. For example, upgrading the Spring SDK dependency from **8.8.x** to **8.9.x** does not require changes to your application code. ### Camunda Process Test (CPT) @@ -105,7 +105,7 @@ CPT is both forward-compatible and backward-compatible with the Orchestration Cl The [Orchestration Cluster REST API](/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview.md) is **backward-compatible**. No breaking changes are introduced to existing endpoints in newer versions of the Orchestration Cluster. For example, if you build a custom client implementation against the **8.8** REST APIs, it continues to work against a newer Orchestration Cluster version such as **8.9**. :::note -Because REST API endpoints are part of the Orchestration Cluster itself, forward compatibility does not apply — your cluster version determines which endpoints are available. +As REST API endpoints are part of the Orchestration Cluster itself, forward compatibility does not apply. Your cluster version determines the available endpoints. ::: ### Recommended upgrade order