The goal of the REST API is to provide access to all relevant interfaces of the engine.

Structure

These documents explain all existing methods in the REST API. For each method they provide:

• An informal description
• HTTP verb and URL
• Possible query, path or message body parameters
• A detailed description of the response content
• Possible response codes
• A brief example request and response

Engine Usage

The methods as described work on the default process engine as given by the available ProcessEngineProvider service.

You may prepend /engine/{name} to any of the methods (unless otherwise documented) to access another engine where {name} is the name of the process engine as returned by ProcessEngine#getName(), e.g., /engine/myEngineName/task.

Error Handling

For every method this documentation gives possible HTTP status codes. The error explanations do not cover all possible error causes that may arise when the request is served, for example, most of the requests will not work properly if there are problems with database access. Any of these undocumented errors will be translated to a HTTP 500 error.

All errors also provide a JSON response body of the form:

  {
    "type" : "SomeExceptionClass",
    "message" : "a detailed message",
    "code" : 10000
  }

Authorization Exceptions

If an already authenticated user interacts with a resource in an unauthorized way, the status code of the response will be set to 403 Forbidden. Details about the unauthorized interaction are provided in the response body.

Type

AuthorizationException

Response Body

{"type" : "AuthorizationException",
 "message" : "The user with id 'jonny' does not have 'DELETE' permission on resource 'Mary' of type 'User'.",
 "code" : 0,
 "userId" : "jonny",
 "permissionName" : "DELETE",
 "resourceName" : "User",
 "resourceId" : "Mary"}

Migration Validation Exceptions

If a migration plan from one process definition version to another is not valid, a migration exception is thrown. It can be a migration plan validation exception where the plan itself is not valid, e.g., it contains an invalid instruction. Or it can be a migrating process instance validation exception when a migration plan cannot be applied to a specific process instance, e.g., an active activity was not mapped by the migration plan.

Migration Plan Validation Exceptions

Type

MigrationPlanValidationException

Response Body

A JSON object with the following properties:

Name	Type	Description
type	String	The type of exception, here MigrationPlanValidationException.
message	String	The error message.
code	Number	The code allows your client application to identify the error in an automated fashion. You can look up the meaning of all built-in codes and learn how to add custom codes in the User Guide.
validationReport	Object	A JSON object containing details about all detected validation errors. Its properties are described below.

Every validation report object contains the following properties:

Name	Type	Description
instructionReports	Array	A JSON array describing a single instruction validation report. Each report object consists of an instruction that is invalid and a failures array containing the validation messages for this instruction.

Example

{
  "type": "MigrationPlanValidationException",
  "message": "ENGINE-23001 Migration plan for process definition 'invoice:1:8aa1533c-23e5-11e6-abb7-f6aefe19b687' to 'invoice:2:8accd012-23e5-11e6-abb7-f6aefe19b687' is not valid:\n\t Migration instruction MigrationInstructionImpl{sourceActivityId='approveInvoice', targetActivityId='assignApprover', updateEventTrigger='false'} is not valid:\n\t\tActivities have incompatible types (UserTaskActivityBehavior is not compatible with DmnBusinessRuleTaskActivityBehavior)\n",
  "code" : 0,
  "validationReport": {
    "instructionReports": [
      {
        "instruction": {
          "sourceActivityIds": [
            "approveInvoice"
          ],
          "targetActivityIds": [
            "assignApprover"
          ],
          "updateEventTrigger": false
        },
        "failures": [
          "Activities have incompatible types (UserTaskActivityBehavior is not compatible with DmnBusinessRuleTaskActivityBehavior)"
        ]
      }
    ]
  }
}

Migrating Process Instance Validation Exceptions

Type

MigratingProcessInstanceValidationException

Response Body

A JSON object with the following properties:

Name	Type	Description
type	String	The type of exception, here MigratingProcessInstanceValidationException.
code	Number	The code allows your client application to identify the error in an automated fashion. You can look up the meaning of all built-in codes and learn how to add custom codes in the User Guide.
message	String	The error message.
validationReport	Object	A JSON object containing details about all detected validation errors. Its properties are described below.

Every validation report object contains the following properties:

Name	Type	Description
processInstanceId	String	The id of the process instance that cannot be migrated when following the migration plan.
failures	Array	An array of general failure messages, which are not related to a specific activity or transition.
activityInstanceValidationReports	Array	An array of JSON objects describing the single activity instance validation errors. Each activity instance validation report consists of a migrationInstruction, if the error is related to an existing migration instruction, the activityInstanceId and sourceScopeId of the activity which cannot be migrated and an array failures, which is a list of all validation error messages for this report.
transitionInstanceValidationReports	Array	An array of JSON objects describing the single transition instance validation errors. Each transition instance validation report consists of a migrationInstruction, if the error is related to an existing migration instruction, the transitionInstanceId and sourceScopeId of the transition which cannot be migrated and an array failures, which is a list of all validation error messages for this report.

Example

{
  "type": "MigratingProcessInstanceValidationException",
  "message": "ENGINE-23004 Cannot migrate process instance '96dc383f-23eb-11e6-8e4a-f6aefe19b687':\n\tCannot migrate activity instance 'approveInvoice:f59925bc-23eb-11e6-8e4a-f6aefe19b687':\n\t\tThere is no migration instruction for this instance's activity\n\tCannot migrate transition instance 'f598897a-23eb-11e6-8e4a-f6aefe19b687':\n\t\tThere is no migration instruction for this instance's activity\n",
  "code": 0,
  "validationReport": {
    "processInstanceId": "96dc383f-23eb-11e6-8e4a-f6aefe19b687",
    "failures": [],
    "activityInstanceValidationReports": [
      {
        "migrationInstruction": null,
        "activityInstanceId": "approveInvoice:f59925bc-23eb-11e6-8e4a-f6aefe19b687",
        "sourceScopeId": "approveInvoice",
        "failures": [
          "There is no migration instruction for this instance's activity"
        ]
      }
    ],
    "transitionInstanceValidationReports": [
      {
        "migrationInstruction": null,
        "transitionInstanceId": "f598897a-23eb-11e6-8e4a-f6aefe19b687",
        "sourceScopeId": "ServiceTask_1",
        "failures": [
          "There is no migration instruction for this instance's activity"
        ]
      }
    ]
  }
}

Parse Exceptions

If the process bpmn resource cannot be parsed during deployment, the deployment of it will fail and the status code of the response will be set to 400 Bad Request. Details about the parsing problems are provided in the response body.

Type

ParseException

Response Body

{
	"type": "ParseException",
	"message": "ENGINE-09005 Could not parse BPMN process. Errors: Exclusive Gateway 'ExclusiveGateway_1' has outgoing sequence flow 'SequenceFlow_0' without condition which is not the default flow.",
	"code" : 0,
	"details": {
		"invoice.bpmn": {
			"errors": [
				{
					"message": "Exclusive Gateway 'ExclusiveGateway_1' has outgoing sequence flow 'SequenceFlow_0' without condition which is not the default flow.",
					"line": 77,
					"column": 15,
					"mainBpmnElementId": "ExclusiveGateway_1",
					"bpmnElementIds": [
						"ExclusiveGateway_1",
						"SequenceFlow_0"
					]
				}
			],
			"warnings": [
				{
					"message": "It is not recommended to use a cancelling boundary timer event with a time cycle.",
					"line": 87,
					"column": 20,
					"mainBpmnElementId": "BoundaryEvent_1",
					"bpmnElementIds": [
						"BoundaryEvent_1"
					]
				}
			]
		}
	}

Query Maximum Results Limit Exceptions

When the maximum results limit of a query is exceeded, an exception is thrown which results in an HTTP status code 400.

Exception codes

Whenever an error occurs, the REST API exposes a property "code" with a numeric code as value in the response body of the failed request. Like this, your client application can handle the error in a reliable and automated fashion. The type property might be too coarse-grained, and the message property might change with newer versions.

You can look up the meaning of all built-in codes and learn how to add custom codes in the User Guide.

Authentication

The REST API ships with an implementation of HTTP Basic Authentication. By default it is switched off (in the rest-api web application and therefore also in the pre-built Camunda 7 distributions). You can activate it by adding a servlet filter as described in the Authentication section.