Using the User REST Interface on the Camunda Platform
This post contains examples of how to use the User REST API of the Camunda BPM engine.
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 User 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:
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: User Resource Options
The OPTIONS /user and OPTIONS /user/{id} REST interfaces retrieves the list of available operations that the current authenticated user can perform on the different REST interfaces. See the documentation for more information.
# Default OPTIONS /user command
$ curl -X OPTIONS http://localhost:8080/engine-rest/user
# Default OPTIONS /user/{ID} command
$ curl -X OPTIONS http://localhost:8080/engine-rest/user/demo
Example 2: Query List of Users
The GET /user REST interface retrieves a list of users 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, firstname, lastname and email.
# Default GET /user REST Interface
$ curl -X GET http://localhost:8080/engine-rest/user
# Add parameter *firstName* to REST Interface
$ curl -X GET 'http://localhost:8080/engine-rest/user?firstName=Demo'
# Add parameter *id* to REST Interface
$ curl -X GET 'http://localhost:8080/engine-rest/user?id=john'
# Add parameter *memberOfGroup* to REST Interface
$ curl -X GET 'http://localhost:8080/engine-rest/user?memberOfGroup=camunda-admin'
Example 3: Query the Number of Users
The GET /user/count REST interface queries the number/count of users that are configured within the Camunda BPM engine. See the documentation for more information and other parameters you can use.
# Default GET /user/count REST Interface
$ curl -X GET http://localhost:8080/engine-rest/user/count
# Add parameter *firstName* to REST Interface
$ curl -X GET 'http://localhost:8080/engine-rest/user/count?firstName=Demo'
Example 4: Create a User
The POST /user/create REST interface creates a new user based on the profile and credentials provided as part of the body. See the documentation for more information.
# Default POST /user/create REST Interface
$ curl -X POST http://localhost:8080/engine-rest/user/create \
-H 'Content-Type: application/json' \
-d '{
"profile": {
"id": "starlord",
"firstName": "Peter",
"lastName": "Quill",
"email": "starlord@avengers.com"
},
"credentials": {
"password": "guardian"
}
}'
Example 5: Get a User’s Profile
The GET /user/{id}/profile REST interface retrieves the profile of the user. See the documentation for more information. The result is an array of user objects with properties: id, firstname, lastname, email and links.
# Default GET /user/{id}/profile REST Interface
$ curl -X GET http://localhost:8080/engine-rest/user/starlord/profile
Example 6: Unlock a User
The GET /user/{id}/unlock REST interface unlocks the user. See the documentation for more information.
# Default GET /user/{id}/unlock REST Interface
$ curl -X GET http://localhost:8080/engine-rest/user/starlord/unlock
Example 7: Update a User’s Profile
The PUT /user/{id}/profile REST interface updates the profile of an existing user. See the documentation for more information.
# Default PUT /user/{id}/profile REST Interface
$ curl -X PUT http://localhost:8080/engine-rest/user/starlord/profile \
-H 'Content-Type: application/json' \
-d '{
"id": "starlord",
"firstName":"New_Peter",
"lastName":"New_Quill",
"email":"new_starlord@avengers.com"
}'
Example 8: Update a User’s Credentials
The PUT /user/{id}/credentials REST interface update the credentials of an existing user. See the documentation for more information.
# Default PUT /user/{id}/credentials REST Interface
$ curl -X PUT http://localhost:8080/engine-rest/user/starlord/credentials \
-H 'Content-Type: application/json' \
-d '{
"password":"updated_password",
"authenticatedUserPassword":"ROOT"
}'
Example 9: Delete a User
The DELETE /user/{id} REST interface deletes the user. See the documentation for more information.
# Default DELETE /user/{id} REST Interface
$ curl -X DELETE http://localhost:8080/engine-rest/user/starlord
Summary
Congratulations! You have successfully used the User 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.
