Using the Group REST Interface on the Camunda Platform

This post contains examples of how to use the Group REST API of the Camunda BPM engine.
- Getting Started
- Start Camunda BPM Platform
- Example 1: Group Resource Options
- Example 2: Query List of Groups
- Example 3: Query the Number of Groups
- Example 4: Create a Group
- Example 5: Get a Group
- Example 6: Update a Group
- Example 7: Group Membership Resource Options
- Example 8: Create a Group Member
- Example 9: Delete a Group Member
- Example 10: Delete a Group
- Summary
A RESTful API is an application program interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. Camunda BPM also provides a REST API to allow other applications to communicate with it and perform several functions.
This post contains examples of how to use the Group REST API of the Camunda BPM engine. There are numerous options in terms of clients you can use like, Postman, Insomnia, and Paw. This post makes use of the curl command to invoke the REST interfaces.
Getting Started
The following list defines the technologies and libraries I used to implement the sample code:
- [Docker][Install_Docker]
- curl
Start Camunda BPM Platform
The following commands are all you need to get a docker container with the Camunda BPM Platform running. The command also defines the container name and the port to expose on the host.
# Creates a container layer over the camunda bpm platform image and then starts it.
$ docker run -d --name camunda -p 8080:8080 camunda/camunda-bpm-platform:latest
# Fetches the logs of the container.
$ docker logs -f camunda
After your Camunda BPM Platform is up and running, you can open the Camunda Admin web application by navigating to the following url in your browser:
http://localhost:8080/camunda-welcome/index.html
# Username: demo
# Password: demo
The REST API is available on the following URL:
http://localhost:8080/engine-rest
Example 1: Group Resource Options
The OPTIONS /group and OPTIONS /group/{id} REST interfaces retrieves the list of available operations that the current authenticated user can perform on the different Group REST interfaces. See the documentation for more information.
# Default OPTIONS /group command
$ curl -X OPTIONS http://localhost:8080/engine-rest/group
# Default OPTIONS /group/{ID} command
$ curl -X OPTIONS http://localhost:8080/engine-rest/group/camunda-admin
Example 2: Query List of Groups
The GET /group REST interface retrieves a list of groups based on the set of parameters. See the documentation for more information and other parameters you can use. The result is an array of user objects with properties: id, name and type.
# Default GET /group REST Interface
$ curl -X GET http://localhost:8080/engine-rest/group
# Add parameter *name* to REST Interface
$ curl -X GET 'http://localhost:8080/engine-rest/group?name=Accounting'
# Add parameter *id* to REST Interface
$ curl -X GET 'http://localhost:8080/engine-rest/group?id=camunda-admin'
# Add parameter *type* to REST Interface
$ curl -X GET 'http://localhost:8080/engine-rest/group?type=WORKFLOW'
Example 3: Query the Number of Groups
The GET /group/count REST interface queries the number/count of groups that are configured within the Camunda BPM engine. See the documentation for more information and other parameters you can use.
# Default GET /group/count REST Interface
$ curl -X GET http://localhost:8080/engine-rest/group/count
# Add parameter *type* to REST Interface
$ curl -X GET 'http://localhost:8080/engine-rest/group/count?type=SYSTEM'
Example 4: Create a Group
The POST /group/create REST interface creates a new group based on the information provided as part of the body. See the documentation for more information.
# Default POST /group/create REST Interface
$ curl -X POST http://localhost:8080/engine-rest/group/create \
-H 'Content-Type: application/json' \
-d '{
"id": "avengers",
"name": "Avengers",
"type": "WORKFLOW"
}'
Example 5: Get a Group
The GET /group/{id} REST interface retrieves a group by id. See the documentation for more information. The result is a group object with properties: id, name and type.
# Default GET /group/{id} REST Interface
$ curl -X GET http://localhost:8080/engine-rest/group/avengers
Example 6: Update a Group
The PUT /group/{id} REST interface updates a group associated with a specific id. See the documentation for more information.
# Default PUT /group/{id} REST Interface
$ curl -X PUT http://localhost:8080/engine-rest/group/avengers \
-H 'Content-Type: application/json' \
-d '{
"id": "avengers",
"name": "The Avengers",
"type": "SYSTEM"
}'
Example 7: Group Membership Resource Options
The OPTIONS /group/{id}/member REST interface retrieves the list of available operations that the current authenticated user can perform on the different Group Membership REST interfaces. See the documentation for more information.
# Default OPTIONS /group/{id}/members command
$ curl -X OPTIONS http://localhost:8080/engine-rest/group/avengers/members
Example 8: Create a Group Member
The PUT /group/{id}/members/{userId} REST interface adds a new member to the group based on the information provided as part of the path. See the documentation for more information.
# Default PUT /group/{id}/members/{userId} command
$ curl -X PUT http://localhost:8080/engine-rest/group/avengers/members/starlord
Example 9: Delete a Group Member
The DELETE /group/{id}/members/{userId} REST interface deletes a member of the group based on the information provided as part of the path. See the documentation for more information.
# Default DELETE /group/{id}/members/{userId} command
$ curl -X DELETE http://localhost:8080/engine-rest/group/avengers/members/starlord
Example 10: Delete a Group
The DELETE /group/{id} REST interface deletes the group. See the documentation for more information.
# Default DELETE /group/{id} REST Interface
$ curl -X DELETE http://localhost:8080/engine-rest/group/avengers
Summary
Congratulations! You have successfully used the Group REST interface to perform a number of functions on the Camunda BPM engine. Follow me on any of the different social media platforms and feel free to leave comments.