Centurion, South Africa info@code2bits.com On Request

Using the User REST Interface on the Camunda Platform

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:

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

Notes

Here are some tips and notes about the examples I showed you:

  • You would have to escape the URL if it has special characters of the shell in it like ampersand ‘&’.
  • You can append the command ‘ jq . ‘ after your curl commands to print the json in a pretty format.

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.