Centurion, South Africa info@code2bits.com On Request

Using the Tenant 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 Tenant 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: Tenant Resource Options

The OPTIONS /tenant and OPTIONS /tenant/{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 /tenant command
$ curl -X OPTIONS http://localhost:8080/engine-rest/tenant

# Default OPTIONS /tenant/{ID} command
$ curl -X OPTIONS http://localhost:8080/engine-rest/tenant/knowhere

Example 2: Query List of Tenants

The GET /tenant REST interface retrieves a list of tenants or specific tenant based on the id parameter. See the documentation for more information and other parameters you can use. The result is an array of user objects with properties: id and name.

# Default GET /user REST Interface
$ curl -X GET http://localhost:8080/engine-rest/tenant

# Add parameter *id* to REST Interface
$ curl -X GET 'http://localhost:8080/engine-rest/tenant?id=knowhere'

Example 3: Query the Number of Tenants

The GET /tenant/count REST interface queries the number/count of tenants that are configured within the Camunda BPM engine. See the documentation for more information and other parameters you can use.

# Default GET /tenant/count REST Interface
$ curl -X GET http://localhost:8080/engine-rest/tenant/count

# Add parameter *id* to REST Interface
$ curl -X GET 'http://localhost:8080/engine-rest/tenant/count?id=knowhere'

Example 4: Create a Tenant

The POST /tenant/create REST interface creates a new tenant based on the id and name 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/tenant/create \
  -H 'Content-Type: application/json' \
  -d '{
		"id": "knowhere",
		"name": "Knowhere"
	}'

Example 5: Get a Tenant

The GET /tenant/{id} REST interface retrieves a specific tenant. See the documentation for more information. The result is an object with properties: id and name.

# Default GET /tenant/{id} REST Interface
$ curl -X GET http://localhost:8080/engine-rest/tenant/knowhere

Example 6: Update a Tenant

The PUT /tenant/{id} REST interface updates an existing tenant. See the documentation for more information.

# Default PUT /user/{id}/profile REST Interface
$ curl -X PUT http://localhost:8080/engine-rest/tenant/knowhere \
  -H 'Content-Type: application/json' \
  -d '{
        "id": "knowhere", 
        "name":"Knowhere 2"
    }'

Example 7: Delete a Tenant

The DELETE /tenant/{id} REST interface deletes a specific tenant. See the documentation for more information.

# Default DELETE /tenant/{id} REST Interface
$ curl -X DELETE http://localhost:8080/engine-rest/tenant/knowhere

Example 8: Tenant Group Membership Resource Options

The OPTIONS /tenant/{id}/group-members REST interface retrieves the list of available operations that the current authenticated user can perform on the different Tenant Group Membership REST interfaces. See the documentation for more information.

# Default OPTIONS /tenant/{id}/group-members command
$ curl -X OPTIONS http://localhost:8080/engine-rest/tenant/knowhere/group-members

Example 9: Create a Tenant Group Member

The PUT /tenant/{id}/group-members/{groupId} REST interface creates a new membership between the group and the tenant. See the documentation for more information.

# Default PUT /tenant/{id}/group-members/{groupId} command
$ curl -X PUT http://localhost:8080/engine-rest/tenant/knowhere/group-members/avengers

Example 10: Delete a Tenant Group Member

The DELETE /tenant/{id}/group-members/{groupId} REST interface deletes the membership between the group and the tenant. See the documentation for more information.

# Default DELETE /tenant/{id}/group-members/{groupId} command
$ curl -X DELETE http://localhost:8080/engine-rest/tenant/avengers/group-members/avengers

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 Tenant 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.