• GET status
• POST process-instances
• GET jobs
• PATCH jobs/{key}

The current scope of this repo is to offer a rest API as a client alternative to zeebe. We could also use it as a single API to interact with camunda 8 entities.

This would enable querying the current state and history through the data in Operate, Optimize and Tasklist. Allow users to interact with their cluster, but also manage it through the console API. This repo could be used as a way to make all API interactions with camunda 8 components consistent through a singular REST API.

Such a change in scope should be reflected in its name as well. For example, camunda-platform-rest-api.

The API itself could consist of entities know from Zeebe like deployments, process-instances, jobs, messages, signals, decisions, etc. It can also consist of entities that are available in the other components like process-definitions, decision-requirements, tasks, clusters, clients, alerts, etc.

The Zeebe REST Client can now be run as a docker container. Easy start up is available via a docker compose file, but that connects the client to a new locally running Zeebe cluster consisting of only a single broker. What if I want to connect this REST client to my already existing Zeebe cluster?

The README should clarify how a user can achieve this.

When a pull request is merged to main, a workflow is run to publish the package to ghcr.io. But, if that pull request was merged by @dependabot then this workflow fails.

During the step Login to the container registry, the following is logged:

Run docker/login-action@v2
with:
    registry: ghcr.io
    username: korthout
    ecr: auto
    logout: true
  env:
    REGISTRY: ghcr.io
    GHCR_USER: korthout
    JAVA_HOME: /opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.6-10/x6[4](https://github.com/korthout/camunda-platform-rest-api/actions/runs/4263903410/jobs/7421242143#step:5:4)
    JAVA_HOME_17_X[6](https://github.com/korthout/camunda-platform-rest-api/actions/runs/4263903410/jobs/7421242143#step:5:6)4: /opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/1[7](https://github.com/korthout/camunda-platform-rest-api/actions/runs/4263903410/jobs/7421242143#step:5:7).0.6-[10](https://github.com/korthout/camunda-platform-rest-api/actions/runs/4263903410/jobs/7421242143#step:5:10)/x64
Error: Username and password required

This does not happen when I merge the pull request.

• Failed pull request
• Successful pull request

Currently the CI only builds and publishes the package. It should also perform some tests so we can be sure that some changes don't break it.

The code examples in the API section of the Docs use the base URL. This may be confusing to users, as the API is not available at the URL https://korthout.github.io/, e.g. The status cannot be retrieved with a GET to https://korthout.github.io/status.

If possible, we should switch this to something like localhost or your-host or similar.

Spotless is automatically formatting the code on a maven build run, but nothing stops us from pushing and merging unstyled code. This often leads to style changes once work starts on a new issue.

We should check the styling in the CI, using mvn spotless:check

Retrieving the cluster status only reports on zeebe currently. However, Operate is now also part of the cluster components that the REST API connects to.

The status should report whether a connection with operate is configured, and if so, whether it is able to connect to it.

This would be useful to simplify the guide to connect to a Self-Managed cluster, because the checking the connection to operate can be done in the same way as checking the connection with zeebe.

This would be useful as this guide is currently quite large and may scare of potential users unnecessarily.

The idea I have now is to:

• run current version of this project in a Testcontainer
• run zeebe broker in a Testcontainer, for example with zeebe-process-test
• write tests that call the API in the Testcontainer
• verify responses
• use zeebe-process-test to verify the state

Common operations

The most common operations that we think we should cover.

• get status
• creating process instances (with variables) #15
• #20
• #21
• #22
• #23
• #24
• #25
• list process instances (active, completed, terminated) (GET process-instances and ?status="activated|completed|terminated")
• #95
• cancel process instance (PATCH process-instances/{key})
• list incidents (GET incidents)
• resolve incident (PATCH incidents/{key})
• set variables for process instance (PATCH process-instances/{key})
• set variables for job (PATCH jobs/{key})
• update job retries (PATCH jobs/{keys})
• start process instance anywhere
• modify process instance

In the future we can also add support for tasks (Tasklist), clients (Console), dashboards (Optimize), projects, files & milestones (Webmodeler #77), etc.

We want your input

Please let us know in a comment what operations you'd like to see next.

#41 added the ability to throw an error for a job. We should make sure that:

• It's documented in the README.md
• It's documented in the docs/api.md
• The OpenAPI spec (in src/main/resources/api.yaml) is updated.

When I try to POST /process-instances, I run into a 500 Interal Server Error.

The following error is logged: java.lang.IllegalArgumentException: variables must not be null

This happens when I use:

 curl --data '{"bpmnProcessId":"onetask"}' \
    --header 'Content-Type: application/json' \
    "localhost:8080/process-instances" | jq
{
  "timestamp": "2022-12-10T17:41:58.442+00:00",
  "status": 500,
  "error": "Internal Server Error",
  "path": "/process-instances"
}

2022-12-10 17:41:58.438 ERROR 1 --- [nio-8080-exec-7] o.a.c.c.C.[.[.[/].[dispatcherServlet]    : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed; nested exception is java.lang.IllegalArgumentException: variables must not be null] with root cause

java.lang.IllegalArgumentException: variables must not be null
	at io.camunda.zeebe.client.impl.command.ArgumentUtil.ensureNotNull(ArgumentUtil.java:22) ~[zeebe-client-java-8.1.5.jar:8.1.5]
	at io.camunda.zeebe.client.impl.command.CreateProcessInstanceCommandImpl.variables(CreateProcessInstanceCommandImpl.java:81) ~[zeebe-client-java-8.1.5.jar:8.1.5]
	at io.camunda.zeebe.client.impl.command.CreateProcessInstanceCommandImpl.variables(CreateProcessInstanceCommandImpl.java:76) ~[zeebe-client-java-8.1.5.jar:8.1.5]
	at com.github.korthout.zeeberestclient.ProcessInstanceController.createProcessInstance(ProcessInstanceController.kt:41) ~[classes/:na]
	at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:na]
	at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(Unknown Source) ~[na:na]
	at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source) ~[na:na]
	at java.base/java.lang.reflect.Method.invoke(Unknown Source) ~[na:na]
	at org.springframework.web.method.support.InvocableHandlerMethod.doInvoke(InvocableHandlerMethod.java:205) ~[spring-web-5.3.23.jar:5.3.23]
	at org.springframework.web.method.support.InvocableHandlerMethod.invokeForRequest(InvocableHandlerMethod.java:150) ~[spring-web-5.3.23.jar:5.3.23]
	at org.springframework.web.servlet.mvc.method.annotation.ServletInvocableHandlerMethod.invokeAndHandle(ServletInvocableHandlerMethod.java:117) ~[spring-webmvc-5.3.23.jar:5.3.23]
	at org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.invokeHandlerMethod(RequestMappingHandlerAdapter.java:895) ~[spring-webmvc-5.3.23.jar:5.3.23]
	at org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.handleInternal(RequestMappingHandlerAdapter.java:808) ~[spring-webmvc-5.3.23.jar:5.3.23]
	at org.springframework.web.servlet.mvc.method.AbstractHandlerMethodAdapter.handle(AbstractHandlerMethodAdapter.java:87) ~[spring-webmvc-5.3.23.jar:5.3.23]
	at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1071) ~[spring-webmvc-5.3.23.jar:5.3.23]
	at org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:964) ~[spring-webmvc-5.3.23.jar:5.3.23]
	at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1006) ~[spring-webmvc-5.3.23.jar:5.3.23]
	at org.springframework.web.servlet.FrameworkServlet.doPost(FrameworkServlet.java:909) ~[spring-webmvc-5.3.23.jar:5.3.23]
	at javax.servlet.http.HttpServlet.service(HttpServlet.java:681) ~[tomcat-embed-core-9.0.65.jar:4.0.FR]
	at org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:883) ~[spring-webmvc-5.3.23.jar:5.3.23]
	at javax.servlet.http.HttpServlet.service(HttpServlet.java:764) ~[tomcat-embed-core-9.0.65.jar:4.0.FR]
	at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:227) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:53) ~[tomcat-embed-websocket-9.0.65.jar:9.0.65]
	at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.springframework.web.filter.RequestContextFilter.doFilterInternal(RequestContextFilter.java:100) ~[spring-web-5.3.23.jar:5.3.23]
	at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117) ~[spring-web-5.3.23.jar:5.3.23]
	at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.springframework.web.filter.FormContentFilter.doFilterInternal(FormContentFilter.java:93) ~[spring-web-5.3.23.jar:5.3.23]
	at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117) ~[spring-web-5.3.23.jar:5.3.23]
	at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.springframework.web.filter.CharacterEncodingFilter.doFilterInternal(CharacterEncodingFilter.java:201) ~[spring-web-5.3.23.jar:5.3.23]
	at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117) ~[spring-web-5.3.23.jar:5.3.23]
	at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:197) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:97) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.catalina.authenticator.AuthenticatorBase.invoke(AuthenticatorBase.java:541) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:135) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:92) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:78) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:360) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.coyote.http11.Http11Processor.service(Http11Processor.java:399) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.coyote.AbstractProcessorLight.process(AbstractProcessorLight.java:65) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:890) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1789) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:49) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.tomcat.util.threads.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1191) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.tomcat.util.threads.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:659) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61) ~[tomcat-embed-core-9.0.65.jar:9.0.65]
	at java.base/java.lang.Thread.run(Unknown Source) ~[na:na]

Currently, the API reference doc is hand written.

It would be cool to generate an OpenAPI specification and use this to generate the API reference documentation. For example, we could generate a website out of this which we host with github-pages where users can explore and try-out the API.

• #38
• use the OpenAPI specification to spin up SwaggerUI as part of the Docker image
• #61

Now that version 0.1.0 is released, we can start making changes for the next release. In order to help users we should version the docs.

This should be possible with Docusaurus' versioning capabilities.

If you cannot access the container image:

$ docker logout
Removing login credentials for https://index.docker.io/v1/

$ docker pull ghcr.io/korthout/camunda-platform-rest-api:latest
Error response from daemon: Head "https://ghcr.io/v2/korthout/camunda-platform-rest-api/manifests/latest": denied: denied

Then you need to log out of GHCR:

$ docker logout ghcr.io

$ docker pull ghcr.io/korthout/camunda-platform-rest-api:latest
latest: Pulling from korthout/camunda-platform-rest-ap

The error may occur when you were logged into GHCR before, but your token expired. You don't need to be logged in to pull any of the camunda-platform-rest-api images, so the problem is resolved by logging out.

Of course, you can log in with a new token (Authenticating with a personal access token (classic)) as well.

The changelog contains an Unreleased section that should become the new version when a new version is released.

As we release new versions automated with the Release workflow, we need to adjust this file in that workflow.

• add a new release section containing the contents of the unreleased section
• add the new tag to the references (compared previous release with the new one)
• adjust the unreleased reference (compares main with new tag)

We may need an additional input (previous release) to update the references correctly

I'm eager to release v0.1.

At the current state of the project, the following should be completed before our first release:

• #9
• Improve the documentation
  • Finish #38
  • #60
  • #61
  • Update the readme to fit #3 (also add community badges)
• #62
• Perhaps more endpoints but that can also be released in 0.2+

Post release we need to:

• Make repo public
• Enable GitHub Pages
• Announce it on the forums / slack and internal

Here is the API spec: https://modeler.cloud.camunda.io/swagger-ui/index.html

Here is a PoC CLI client for it: https://github.com/camunda-community-hub/web-modeler-cli

We already have a workflow to deploy (publish) the docker image artifact. However, in the current state it will take the version from the pom. The release version should be decoupled from source using the maven revision property.

Note that openapi.yaml also contains the specific version.

Let's use Bors for this, while Github Merge Queues are not yet publicly available.

I'd like to see an image built for arm64.

If I create a process instance with variables:

curl \
  --data '{"bpmnProcessId":"onetask","variables":{"foo":true,"bar":2,"baz":{}}}' \
  --header 'Content-Type: application/json' \
  "localhost:8080/process-instances"

And activate the jobs without specifying fetchVariables, then the variables are an empty object {}:

curl "localhost:8080/jobs?type=task" | jq
{
  "data": {
    "jobs": [
      {
        "key": 2251799813685425,
        "type": "task",
        "processInstanceKey": 2251799813685417,
        "bpmnProcessId": "onetask",
        "processDefinitionVersion": 1,
        "processDefinitionKey": 2251799813685254,
        "elementId": "Activity_0q59ktq",
        "elementInstanceKey": 2251799813685424,
        "customHeaders": {},
        "worker": "default",
        "retries": 3,
        "deadline": 1670695324179,
        "variables": {}
      }
    ]
  },
  "error": null
}

But, if I specify the fetchVariables, then the variables are provided correctly:

curl "localhost:8080/jobs?type=task&fetchVariables=foo,baz,bar" | jq
{
  "data": {
    "jobs": [
      {
        "key": 2251799813685413,
        "type": "task",
        "processInstanceKey": 2251799813685405,
        "bpmnProcessId": "onetask",
        "processDefinitionVersion": 1,
        "processDefinitionKey": 2251799813685254,
        "elementId": "Activity_0q59ktq",
        "elementInstanceKey": 2251799813685412,
        "customHeaders": {},
        "worker": "default",
        "retries": 3,
        "deadline": 1670695182477,
        "variables": {
          "bar": 2,
          "baz": {},
          "foo": true
        }
      }
    ]
  },
  "error": null
}

There appears to be a difference between the openapi.yaml file and the specification used to produce the Swagger UI.

For example, the Swagger UI in version 0.1.0 does not contain the API stability warning.

I wonder whether Swagger UI is a useful feature or irrelevant with the full specification being available from the Docs.

📣 Please let me know what you think 👍 (I like Swagger UI) / 👎 (I don't need Swagger UI)

The API may see breaking changes in its future. We should make sure these don't break functionality for existing users. Let's version the API so users can update without having to overhaul their existing code.

Note that at the start the API should be version v0 and breaking changes will be allowed until v1 is released.

The Docs and the README refer to the API as Consistent. Consistent typically means something else in software than what is meant here. This leads to confusion.

Let's call the API unified, as it unifies the different APIs into a single API.

#37 added the ability to fail a job. We should make sure that:

• It's documented in the README.md
• It's documented in the docs/api.md
• The OpenAPI spec (in src/main/resources/api.yaml) is updated.