Skip to main content
Version: Next

Migrate to the Camunda 8 API

This document offers a comprehensive guide to migrate from Camunda's V1 component REST APIs (the Tasklist REST API, for example) to the V2 Camunda 8 REST API.

Camunda is streamlining the developer experience by creating a unified REST API for Zeebe, Operate, Tasklist, and the Identity components with endpoint parity. This will be a single REST API for the orchestration cluster for a consistent and intuitive API experience to help your teams develop process automation solutions faster.

note

The 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.

Overtime, there will be a deprecation process for the individual component APIs starting with the former Operate and Tasklist APIs. These will continue to be in the product for the short-term, but it is recommended to begin the adoption of the new API. In addition, we will begin to deprecate several Zeebe gPRC endpoints as well. See the official blog announcement.

Migrate endpoints​

This section considers all public endpoints existing in the component REST APIs and the Camunda 8 API counterparts or required migration changes.

General changes​

  • The new API can be found at <cluster>/v2/…> instead of <cluster>/v1/…>.
  • All endpoints are no longer separated by component concerns and all endpoints receive similar support. For example, process definitions, user tasks, and user authorizations were previously spread across separate Tasklist, Operate, and Identity APIs.
  • Naming, response codes, and type handling have been streamlined for all endpoints to provide a consistent UX.
  • Endpoints with similar concerns (variable search, for example) have been consolidated into single endpoints.

Name changes and mappings​

The following conventions apply to all attributes:

  • key and id fields contain the entity as a prefix, for example, userTaskKey, processDefinitionId. This applies when referencing other resources like formKey in the user task entity, in the respective entities themselves like userTaskKey in the user task entity.
  • The full entity is the prefix to avoid confusion, for example processDefinitionKey instead of processKey (the latter could be interpreted as process instance or process definition).
  • Other attributes of entities themselves have no prefix to avoid clutter, for example version in the process definition entity. In other resources, they have to be referenced with a prefix, like processDefinitionVersion in the process instance entity.
  • The bpmnProcessId is now called processDefinitionId to be easily relatable to the entity (process definition) and the accompanying processDefinitionKey.
  • The decisionKey and dmnDecisionKey are now aligned to decisionDefinitionKey, the decisionId and dmnDecisionId to decisionDefinitionId. Similar to the processDefinitionId, those attributes are now related to the entity decisionDefinition.

Tasklist​

Search tasks​

  • V1 endpoint: POST /v1/tasks/search
  • V2 endpoint: POST /v2/user-tasks/search
  • Filter attribute assigned (boolean) removed
    • Use filter attribute assignee with condition { "$exists": false }
  • Filter attribute assignees (string[]) removed
    • Use filter attribute assignee with condition { “$in”: [ “xyz”, ... ] }
  • Filter attribute taskDefinitionId renamed
    • Use filter attribute elementId
  • Filter attribute candidateGroups (string[]) removed
    • Use filter attribute candidateGroup with condition { “$in”: [ “xyz”, ... ] }
  • Filter attribute candidateUsers (string[]) removed
    • Use filter attribute candidateUser with condition { “$in”: [ “xyz”, ... ] }