Skip to main content

Overview

We want to provide you with the information you need to successfully migrate from our GraphQL API to our new REST API version. In this document, we'll explain the differences between the two APIs and provide guidance on how to make the switch.

GraphQL has been a popular and valuable tool for many of our customers, but we recognize that there are certain advantages to using a RESTful architecture. Our new REST API version provides a more structured and predictable way of accessing our data, which should lead to improved performance and greater reliability.

It's worth noting that all of our other APIs use REST, so moving to a RESTful architecture will align this API with the rest of our ecosystem. This will make it easier to maintain and enhance our APIs over time, as well as providing a more consistent experience for API customers.

GraphQL operation to REST API endpoint mapping

Queries​

Task​

Instead of task GraphQL query:

# Get one task by id. Returns task or error when task does not exist.
task(id: String!): Task!

The following get task endpoint should be used:

curl -X 'GET' \
  'http://{host}/v1/tasks/{taskId}' \
  -H 'accept: application/json'
  -H 'Cookie: TASKLIST-SESSION={tasklistSessionId}'
note

The following fields in REST API response were renamed compared to the equivalent GraphQL response:

Tasks​

Instead of tasks GraphQL query:

# Get list of tasks based on `TaskQuery`.
tasks(query: TaskQuery!): [Task!]!

The following search tasks endpoint should be used:

curl -X 'POST' \
  'http://{host}/v1/tasks/search' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: TASKLIST-SESSION={tasklistSessionId}' \
  -d '{
  "state": "CREATED",
  "assigned": true
}'
note

Please note that several field names in request body and response were changed in REST API comparing to the equivalent GraphQL input/response models, in order to improve the consistency and clarity of our API:

Variable​

Instead of variable GraphQL query:

# Get the variables by variable id
variable(id: String!): Variable!

The following get variable endpoint should be used:

curl -X 'GET' \
  'http://{host}/v1/variables/{variableId}' \
  -H 'accept: application/json' \
  -H 'Cookie: TASKLIST-SESSION={tasklistSessionId}'

Variables​

Instead of variables GraphQL query:

# Get a collection of Variables by name
variables(taskId: String!, variableNames: [String!]!): [Variable!]!

The following search task variables endpoint should be used:

curl -X 'POST' \
  'http://{host}/v1/tasks/{taskId}/variables/search' \
  -H 'accept: application/json' \
  -H 'Cookie: TASKLIST-SESSION={tasklistSessionId}' \
  -d '{
    "variableNames": [
      "varA", "varB"
    ]
  }'

Form​

Instead of form GraphQL query:

# Get task form by formId and processDefinitionId
form(id: String!, processDefinitionId: String!): Form

The following get form endpoint should be used:

curl -X 'GET' \
  'http://{host}/v1/forms/{formId}?processDefinitionKey={processDefinitionKey}' \
  -H 'accept: application/json' \
  -H 'Cookie: TASKLIST-SESSION={tasklistSessionId}'
note

Note that processDefinitionKey query parameter in HTTP request represents the same value as form.processDefinitionId, and in REST API response FormResponse.processDefinitionKey field is the renamed equivalent of Form.processDefinitionId.

Mutations​

Claim task​

Instead of claimTasks GraphQL mutation:

# Claim a task with `taskId` to `assignee`. Returns the task.
claimTask(taskId: String!, assignee: String, allowOverrideAssignment: Boolean): Task!

The following assign task endpoint should be used:

curl -X 'PATCH' \
  'http://{host}/v1/tasks/{taskId}/assign' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: TASKLIST-SESSION={tasklistSessionId}'

Unclaim task​

Instead of unclaimTasks GraphQL mutation:

# Unclaim a task with taskId. Returns the task.
unclaimTask(taskId: String!): Task!

The following unassign task endpoint should be used:

curl -X 'PATCH' \
  'http://{host}/v1/tasks/{taskId}/unassign' \
  -H 'accept: application/json' \
  -H 'Cookie: TASKLIST-SESSION={tasklistSessionId}'

Complete task​

Instead of completeTasks GraphQL mutation:

# Complete a task with taskId and optional variables. Returns the task.
completeTask(taskId: String!, variables: [VariableInput!]!): Task!

The following complete task endpoint should be used:

curl -X 'PATCH' \
  'http://{host}/v1/tasks/{taskId}/complete' \
  -H 'accept: application/json' \
  -H 'Cookie: TASKLIST-SESSION={tasklistSessionId}'