Working with multiple APIs that use different protocols and schemas can be challenging, which is why we’ve taken the initiative to streamline Camunda product APIs and eventually provide a single REST API for the Zeebe, Operate, Tasklist, Optimize, and Identity components.
While Zeebe’s current gRPC API offers benefits for microservices architectures, such as bidirectional data streaming and support for high performance use cases, many developers find that gRPC has a steep learning curve. In addition, operating gRPC makes it harder to install and configure Camunda in your organization.
As the first step for a unified Camunda 8 API, we’re reducing the learning curve and making installation easier by building a comprehensive REST API for Zeebe. This API will provide three categories of endpoints:
- User task management: Zeebe will become responsible for managing the state of user tasks as we introduce a new user task type: Zeebe User Tasks. Along with this shift, we’ll update the Zeebe API with REST endpoints that are dedicated to user task management. We’re working to ensure that migration from the Tasklist API to the Zeebe API is smooth, and the previous task type will still be supported.
- Migrated gRPC endpoints: We will iteratively migrate gRPC endpoints to REST endpoints, prioritizing endpoints based on how critical they are and which use cases they support. This phased approach ensures a systematic and thorough transition, minimizing disruptions for developers.
- GET endpoints for entities: We will provide additional endpoints to retrieve real-time process entity states directly from Zeebe (process entities are things like user tasks, process instances, variables, and so on). These GET methods play a crucial role in enabling developers to implement runtime interactions, where the current state of an entity is essential for deciding the next action.
Facilitating high-performance use cases
We originally adopted gRPC for Zeebe because it offers advantages for low-latency and high-throughput use cases. Therefore, we will retain the gRPC endpoints tailored to these use cases. We’ll provide guidance for migrating to the new endpoints and recommendations on when you should use the REST API or the gRPC API.
Once all gRPC endpoints except Job-Push have been migrated to the Zeebe REST API, then after two minor releases we will deprecate and remove endpoints not needed for low-latency use cases.
If you use supported clients or SDKs, the migration path will be easy to follow. Clients will support migration, and all you need to do is to check if your network has opened the correct ports for the REST API. We aim to provide a seamless migration path that minimizes the amount of effort needed for you to adopt the REST API.
In a future release, we will make gRPC inactive in the Zeebe Gateway by default. Still, we will provide flexibility to enable job streaming via gRPC when your use cases require reduced job activation latency.
New supported clients and SDKs
As part of our strategy to enhance your user experience and simplify integration processes, we are introducing officially supported Software Development Kits (SDKs) and updated Zeebe clients in multiple programming languages.
In the upcoming release, we will officially support NodeJS, unifying interactions across diverse APIs and delivering a seamlessly integrated experience for all of Camunda 8.
The new Spring Zeebe SDK (spring-boot-starter-camunda-sdk) will be released and fully supported to help you easily use the Zeebe Java Client in your Spring or Spring Boot projects. This SDK will start as a fork of the community-maintained Spring Zeebe Client. Later this year, we’ll expand the Spring Zeebe SDK to deliver a Camunda Spring SDK that, similar to the NodeJS SDK, will provide a unified experience for interacting with all Camunda APIs in Java Spring. We recommend migrating to the officially supported Spring Zeebe and Camunda Spring SDK.
The new Spring Zeebe SDK and Zeebe Java client will support both the Zeebe gRPC API and the REST API of Zeebe, providing easy migration between protocols and easier development of client applications.
In addition to new clients and SDKs, we will provide an OpenAPI spec and Postman collections for an easy getting-started experience.
Moving the Go and zbctl clients to the community
After the Zeebe REST API is completed, we will move the Go and zbctl clients to the Camunda Community Hub. This means that these clients won’t be officially supported by Camunda anymore, so Camunda Engineering will stop fixing bugs and building new features for the clients, and Camunda Support will no longer support them. The clients will be available to the community for you to fork and extend.
With the REST API, the interaction with the Zeebe engine will be much easier; you will be able to work with it in the same way you work with any other REST service. Use the OpenAPI definition, the supported Postman collection, or cURL for an easy getting-started experience and implement API calls in your code. We also recommend giving the new clients and SDKs a try.
If you are interested in maintaining the community projects, contact us by filling out this form in the Camunda Community Hub!
What’s next
We’ll gradually be rolling out API changes, starting with user task endpoints. Stay tuned for a blog post explaining how user task management will be handled in Zeebe. And if you have any questions, visit us at the Camunda Forum.
Start the discussion at forum.camunda.io