id | title | description |
---|---|---|
migrate-to-camunda-api |
Migrate to the Camunda 8 API |
Migrate from Camunda's V1 component REST APIs to the V2 Camunda 8 REST API to interact with Camunda 8 clusters, activate jobs, and run user task state operations. |
import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem";
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.
This section considers all public endpoints existing in the component REST APIs and the Camunda 8 API counterparts or required migration changes.
<Tabs groupId="endpoints" defaultValue="all-endpoints" queryString values={ [ {label: 'All endpoints', value: 'all-endpoints', }, {label: 'Endpoints querying for data', value: 'query-endpoints', }, ] }>
- 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.
- Unified search request structure.
- Attributes
filter
,page
, andsort
on root level. - Endpoint-specific filter attributes in the filter object, not at the root level.
- Pagination information in the
page
object. For example, the attributesfrom
,limit
,searchBefore
, andsearchAfter
. - Sorting configuration in sort object array, each object containing the field name and order (descending or ascending).
- Attributes
- Unified search response structure.
- Attributes
items
andpage
on root level. - List of endpoint-specific response items in
items
attribute. - Page information in
page
attribute, for example the attributestotalItems
,firstSortValues
, andlastSortValues
to use insearchBefore
andsearchAfter
in follow-up requests.
- Attributes
The following conventions apply to all attributes:
key
andid
fields contain the entity as a prefix, for example,userTaskKey
,processDefinitionId
. This applies when referencing other resources likeformKey
in the user task entity, in the respective entities themselves likeuserTaskKey
in the user task entity.- The full entity is the prefix to avoid confusion, for example
processDefinitionKey
instead ofprocessKey
(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 calledprocessDefinitionId
to be easily relatable to the entity (process definition) and the accompanyingprocessDefinitionKey
. - The
decisionKey
anddmnDecisionKey
are now aligned todecisionDefinitionKey
, thedecisionId
anddmnDecisionId
todecisionDefinitionId
. Similar to theprocessDefinitionId
, those attributes are now related to the entitydecisionDefinition
.
- V1 endpoint:
POST /v1/tasks/search
- V2 endpoint:
POST /v2/user-tasks/search
<Tabs groupId="tasklist" defaultValue="input-adjustments" queryString values={ [ {label: 'Input adjustments', value: 'input-adjustments', }, {label: 'Output adjustments', value: 'output-adjustments', }, ] }>
- Filter attribute
assigned (boolean)
removed- Use filter attribute
assignee
with condition{ "$exists": false }
- Use filter attribute
- Filter attribute
assignees (string[])
removed- Use filter attribute
assignee
with condition{ “$in”: [ “xyz”, ... ] }
- Use filter attribute
- Filter attribute
taskDefinitionId
renamed- Use filter attribute
elementId
- Use filter attribute
- Filter attribute
candidateGroups (string[])
removed- Use filter attribute
candidateGroup
with condition{ “$in”: [ “xyz”, ... ] }
- Use filter attribute
- Filter attribute
candidateUsers (string[])
removed- Use filter attribute
candidateUser
with condition{ “$in”: [ “xyz”, ... ] }
- Use filter attribute