Обзор
REST API дает доступ ко всем основным интерфейсам движка.
Структура
Справочник описывает все методы REST API. Для каждого метода приводятся:
-
Описание
-
HTTP-глагол и URL
-
Возможные параметры запроса (query), пути (path) или тела сообщения (message body)
-
Подробное описание содержимого ответа
-
Возможные коды ответа
-
Краткий пример запроса и ответа
Использование движка
Описанные методы работают с процессным движком по умолчанию, который возвращает доступный сервис ProcessEngineProvider.
Чтобы обратиться к другому движку, добавьте к пути метода префикс /engine/{name} (если не указано иное). Здесь {name} означает имя процессного движка, которое возвращает ProcessEngine#getName(), например /engine/myEngineName/task.
Обработка ошибок
Для каждого метода в справочнике перечислены возможные коды HTTP-статуса. Описаны не все причины ошибок при обработке запроса: например, большинство запросов не выполнится, если недоступна база данных. Все такие недокументированные ошибки возвращаются как ошибка HTTP 500.
У каждой ошибки есть тело ответа в формате JSON такого вида:
{
"type" : "SomeExceptionClass",
"message" : "a detailed message",
"code" : 10000
}
Исключения валидации миграции
Если план миграции с одной версии определения процесса на другую некорректен, выбрасывается исключение миграции. Это исключение валидации плана миграции (migration plan validation exception), если некорректен сам план, например содержит некорректную инструкцию. Или исключение валидации мигрируемого экземпляра процесса (migrating process instance validation exception), если план миграции нельзя применить к конкретному экземпляру процесса, например активное активити не сопоставлено в плане миграции.
Исключения валидации плана миграции
Тело ответа
JSON-объект со следующими свойствами:
| Имя | Тип | Описание |
|---|---|---|
type |
String |
Тип исключения, здесь MigrationPlanValidationException. |
message |
String |
Сообщение об ошибке. |
code |
Number |
По коду клиентское приложение может распознать ошибку автоматически. Значения встроенных кодов и способ добавить собственные коды описаны в Руководстве пользователя. |
validationReport |
Object |
JSON-объект с подробностями обо всех найденных ошибках валидации. Его свойства описаны ниже. |
Каждый объект отчёта о валидации содержит следующие свойства:
| Имя | Тип | Описание |
|---|---|---|
instructionReports |
Array |
JSON-массив отчетов о валидации отдельных инструкций. Каждый объект отчета состоит из некорректной инструкции instruction и массива failures, содержащего сообщения валидации для этой инструкции. |
Пример
{
"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)"
]
}
]
}
}
Исключения валидации мигрируемого экземпляра процесса
Тело ответа
JSON-объект со следующими свойствами:
| Имя | Тип | Описание |
|---|---|---|
type |
String |
Тип исключения, здесь MigratingProcessInstanceValidationException. |
code |
Number |
По коду клиентское приложение может распознать ошибку автоматически. Значения встроенных кодов и способ добавить собственные коды описаны в Руководстве пользователя. |
message |
String |
Сообщение об ошибке. |
validationReport |
Object |
JSON-объект с подробностями обо всех найденных ошибках валидации. Его свойства описаны ниже. |
Каждый объект отчёта о валидации содержит следующие свойства:
| Имя | Тип | Описание |
|---|---|---|
processInstanceId |
String |
Идентификатор экземпляра процесса, который нельзя мигрировать по этому плану миграции. |
failures |
Array |
Массив общих сообщений об ошибках, не связанных с конкретным активити или переходом. |
activityInstanceValidationReports |
Array |
Массив JSON-объектов, описывающих отдельные ошибки валидации экземпляров активностей. Каждый отчет о валидации экземпляра активности состоит из migrationInstruction (если ошибка связана с существующей инструкцией миграции), activityInstanceId и sourceScopeId активити, которое нельзя мигрировать, и массива failures со всеми сообщениями об ошибках валидации для этого отчета. |
transitionInstanceValidationReports |
Array |
Массив JSON-объектов, описывающих отдельные ошибки валидации экземпляров переходов. Каждый отчёт о валидации экземпляра перехода состоит из migrationInstruction (если ошибка связана с существующей инструкцией миграции), transitionInstanceId и sourceScopeId перехода, который нельзя мигрировать, и массива failures со всеми сообщениями об ошибках валидации для этого отчета. |
Пример
{
"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)
Если ресурс BPMN не удается разобрать при развертывании, развертывание завершается ошибкой и возвращается код статуса 400 Bad Request. Подробности о проблемах разбора приводятся в теле ответа.
Тело ответа
{
"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"
]
}
]
}
}
}
Исключения превышения лимита максимального числа результатов запроса
Когда лимит максимального числа результатов запроса превышен, выбрасывается исключение и возвращается код HTTP-статуса 400.
Коды исключений
При ошибке REST API возвращает в теле ответа свойство "code" с числовым кодом.
По нему клиентское приложение может надежно и автоматически обработать ошибку.
Свойство type для этого слишком общее, а текст message может меняться от версии к версии.
Значения встроенных кодов и способ добавить собственные коды описаны в Руководстве пользователя.
Аутентификация
REST API поставляется с реализацией HTTP Basic Authentication. По умолчанию она отключена в веб-приложении REST API и, соответственно, в готовых дистрибутивах OpenBPM Engine. Чтобы ее включить, добавьте сервлет-фильтр, как описано в разделе Аутентификация.
Документация создана на основе Camunda 7 Docs (Camunda, docs.camunda.org) и распространяется по лицензии Creative Commons Attribution-ShareAlike 3.0 Unported.