Skip to main content
Version: 8.3

GraphQL to REST API migration

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 can improve 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!

Use the following get task endpoint:

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!]!

Use the following search tasks endpoint:

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!

Use the following get variable endpoint:

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!]!

Use the following search task variables endpoint:

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

Use the following get form endpoint:

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!

Use the following assign task endpoint:

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!

Use the following unassign task endpoint:

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!

Use the following complete task endpoint:

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