At Camunda, we constantly strive to improve the developer and customer experience with our platform. As part of our ongoing effort to streamline and unify our product, we are excited to announce a series of changes to the APIs.
These changes focus on simplifying the API experience and streamlining API interactions to align with our customer’s evolving needs. We understand that API updates can sometimes be daunting, but we are committed to supporting you every step of the way.
Below, we outline what’s changing and how we’ll assist you in transitioning smoothly.
Why these changes to the Camunda API?
As part of this ongoing initiative, we aim to provide a unified experience with a single REST API for the orchestration cluster to simplify installation, onboarding, and accelerate the development process. By migrating and harmonizing endpoints in the Camunda 8 REST API, we make it easier to access resources with a consistent experience while ensuring all endpoints are secure with authentication and fine-grained resource authorization.
The Camunda 8 REST API will offer parity to endpoints that were previously available in the component APIs (Zeebe, Operate, Tasklist, Identity, Optimize), actuator endpoints (usage metrics, backups, cluster scaling, etc.), and expand beyond with the new capabilities. This will be a single API to manage the orchestration cluster.
Administration and Web Modeler APIs will not be part of the Camunda 8 REST API, as these are platform APIs outside the cluster’s scope.
What’s changing ?
Camunda 8.6 (live today)
Introduction of the Camunda 8 REST API
With the most recent 8.6 release, customers can already use the first part of the Camunda 8 REST API to manage process entities (processes, decisions, user tasks, forms). For easier installation and configuration, all the functionalities (except Job Push) that were previously available in Zeebe gRPC API are now available as REST endpoints.
The Camunda 8 REST API will be the default API going forward for new functionalities that we’re building in the API, and new process management endpoints (e.g., Message Correlation with Result) will only be available with this API.
The process management endpoints in Camunda 8 REST API are already available in all officially supported API Clients—Zeebe Java Client, Spring Zeebe SDK, and JavaScript SDK.
Camunda 8.7 (planned for February 2025)
Camunda 8 REST API for querying and permission management
We will release query endpoints for process entities (processes, decisions, user tasks, and forms) that will replace component APIs (Tasklist, Operate) going forward. We will also include endpoints to manage and query users and resource permissions in an orchestration cluster. All the Camunda 8 REST API endpoints will support resource-based authorizations to enable fine-grained permissions.
As part of this initiative, we’re aligning our API terminology so that the same technical asset has an identical, easy-to-understand, descriptive property name. This will simplify interactions and make the naming conventions clearer and more explicit.
Advanced search for Query API
We will provide a flexible API for building advanced, fine-grained filters to enhance the API experience and ease the implementation of advanced use cases. This will enable our customers to efficiently search and filter Camunda entities using logical and comparison operators. The first endpoints supporting this capability will be process instance search and user task search. Subsequently, we will expand this functionality to other search endpoints.
Updated Camunda SDKs
Starting with 8.7, the Zeebe Java client and Spring SDK will become the new Camunda clients. This change introduces a refreshed client structure designed to enhance the developer experience, introduce new features, and maintain compatibility with current codebases.
The Camunda Java client and Spring SDK are built directly on the Zeebe client infrastructure (Zeebe Java Client and Zeebe Spring SDK), which may already be familiar to you. This new release reflects our ongoing commitment to a unified API experience by renaming and expanding prior Zeebe clients to integrate with the Camunda API easily.
Deprecation of the Operate API and Tasklist API
We will begin the deprecation process for the Operate and Tasklist REST API. These APIs will still be available with Camunda 8.7 and 8.8 but won’t be recommended for new implementations. Starting in Camunda 8.9, these APIs will be completely removed.
With the 8.7 release, customers can begin migrating to the Camunda 8 REST API for querying to prepare for this change and solve the same use cases.
Removal of the Tasklist GraphQL API
The Tasklist GraphQL API will be removed from the product at the conclusion of the deprecation process of Tasklist GraphQL API. Customers who haven’t had a chance yet to migrate can use Camunda 8 REST API for User Task interactions (both management and querying).
Deprecation of Job-based User Tasks querying
User tasks can be implemented with two different task types: the Job-worker and Camunda User Task (formerly known as Zeebe User Task). The differences in the implementation are as follows:
- The
Job-workertype is a job with a list of custom headers visible in the query API. This type of user task is managed in Tasklist, and changes made before completing a user task are not replicated to another region (in case of multi-region deployment) or exported on the log stream (not available to custom exporters). This user task type is supported only with Tasklist REST API.
- The
Camunda User Taskis an engine-native concept where Zeebe manages the state of the user task. This means that data replication and resilience are fully supported, and any changes to user tasks are available to custom exporters. Additionally, with the 8.7 release, customers can react to task lifecycle state changes with task listeners. This user task type is supported with Camunda 8 REST API for management and querying, and Tasklist API for querying.
To streamline the development of process applications, we recommend using Camunda User Tasks in your process definitions. Starting with 8.7, Camunda modelers will automatically apply the Camunda User Task and display a warning message for each Job-worker user task.
The Job-worker user tasks will be available for querying until the 8.9 release. With 8.9 and later, customers can use the Job-worker implementation of user tasks as standard jobs with headers to enable open architecture and composable solutions.
Deprecation of Zeebe gRPC API endpoints not necessary for performance use cases
We recognize and value the advantages that gRPC brings to the product. However, it’s challenging for some customers due to network requirements and gRPC is not as popular as other protocols.
With this release, several Zeebe gRPC endpoints will be deprecated. Key gRPC endpoints necessary for high-throughput and low-latency applications will remain available to ensure peak performance for specific use cases. Based on benchmark comparisons between REST and gRPC, the final list of retained gRPC endpoints will be confirmed with the 8.7 release. Selected endpoints will remain active, with the others scheduled for removal in the 8.9 release.
Camunda 8.8 (planned for April 2025)
Harmonization and unification of the system API
To simplify platform operations, we will harmonize the system API within the Camunda 8 REST API, ensuring all endpoints are secured and supporting resource authorizations. Endpoints like Prometheus metrics, usage metrics, backups and others will be unified and provided for the entire orchestration cluster, not just per component anymore.
By harmonize, we mean there is a single endpoint to trigger specific platform operations for the entire cluster (e.g., backup) in the /system API path and unified, as the terminology will be the same for different technical components (e.g., Prometheus metrics).
Camunda Process Test
We will release the Camunda Process Test for Java and Spring projects, enabling developers to test their processes comprehensively using Camunda 8 API endpoints. With features like different types of assertions, test isolation, or mocking BPMN elements, developers can now confidently test their processes within their preferred environments.
Camunda JS SDK for the browser
With Camunda 8.8, we will release a new version of the Camunda JS SDK that runs both server-side via Node.js and natively in the web browser. This unlocks greater architectural flexibility for your applications. The Camunda JS SDK will support the full Camunda 8 REST API.
Camunda 8.9 (planned for October 2025)
Zeebe gRPC API and Zeebe REST API removed
With this release, previously deprecated Zeebe gRPC API endpoints will be removed. We will keep endpoints meant for high-throughput and low-latency use cases.
Since the Camunda 8 REST API includes all the same endpoints for process management as the Zeebe REST API since the 8.6 release, we will remove the Zeebe REST API to make it easier to identify the proper API for process management.
In line with Camunda 8’s shift to a REST-first approach, the Zeebe gRPC API will be disabled by default for new clusters in self-managed installations, allowing for REST-only communication. For those who need it, enabling gRPC will be straightforward via configuration settings.
Operate REST API and Tasklist REST API removed
To further streamline Camunda 8’s architecture and API experience, we will remove previously deprecated APIs—Operate and Tasklist. Customers can migrate to the Camunda 8 REST API, which provides the same functionality and goes beyond to facilitate advanced use cases.
With the removal of the Tasklist REST API, job-based user tasks will no longer be supported for querying and task management. This type of user task will be handled as a standard job with custom headers, and the Job API can be used to manage these tasks. For customers who require task lifecycle support and task querying, we recommend using the Camunda User Task type.
Real-time GET endpoints for user tasks and variables
This initiative will provide additional endpoints to retrieve the runtime state of process entities (user tasks, variables). These GET methods play a crucial role in enabling users to implement runtime interactions, where the current state of an entity is essential for deciding the next action. We’re still discovering use cases and requirements for this functionality, so if you have feedback about this, please add a comment here.
Key dates and actions
To help our customers stay on track with these changes, here’s a quick summary of important updates:
- Camunda 8.7: Start migration to Camunda 8 REST API for querying.
- Camunda 8.8: Harmonized Monitoring API available.
- Camunda 8.9: Removal of Zeebe REST API, specified Zeebe gRPC endpoints, Operate API, and Tasklist API.
In relation to the roadmap, we intend to outline general plans with planned releases. This does not represent commitments, as deliverables are subject to a number of risks and uncertainties, many of which involve factors or circumstances beyond Camunda’s control.
Migration and support
We understand that these changes may raise questions about compatibility and migration. To ensure a seamless transition, we will provide comprehensive step-by-step migration guides, documentation for moving from V1 to V2 APIs, and instructions on using new clients to simplify interactions. The migration guides will also highlight the differences between both APIs.
These resources will also include detailed instructions on migrating from job-based user tasks to the Camunda user tasks to enable advanced Human Task Orchestration use cases.
As we prepare for these changes, we want to assure our customers that we are here to support them throughout the transition. Don’t hesitate to visit our forum as well to check how others are approaching migration and share your best practices.
What’s next?
We encourage all customers to begin reviewing the Camunda 8 REST API and reach out to us with any questions. Our product, engineering, and consulting teams are here to assist with any concerns or clarifications you may have.
We look forward to seeing how these changes will ease onboarding and installation while streamlining product operations.
Stay tuned for more updates on our blog and detailed documentation on step-by-step migration, which will be available together with the Camunda 8.7 release.
Start the discussion at forum.camunda.io