Qodex.ai

Web Modeler public API (REST)

Number of APIs: 0

🚀 Overview

Web Modeler's beta API was deprecated and removed in the 8.5 release of Web Modeler.

Web Modeler provides a REST API at /api/. Clients can access this API by passing a JWT access token in an authorization header Authorization: Bearer .

NOTE: A detailed API description is available as OpenAPI specification at https://modeler.camunda.io/swagger-ui/index.html for SaaS and at http://localhost:8070/swagger-ui.html for Self-Managed installations.

Take a closer look at Camunda's Modeler API (REST) documentation.

💪 What do you need to make it work?

All requests to the Modeler API require authentication.

This Qodex collection is configured to automatically handle the authentication process if:

  • You are using the SaaS offering of Camunda

  • You provide an API client ID and secret

If you're using a Self-Managed instance of Camunda, you may need to manually request an authentication token and include it in the headers of your requests.

1. Configure an API client

To interact with Camunda 8 programmatically without using Camunda Console, create client credentials in the organization settings under the Administration API tab.

Client credentials are created for an organization, and therefore can access all Camunda 8 clusters of this organization.

After client credentials are created, the Client Secret is only shown once. Save this Client Secret somewhere safe.

2. Configure a Qodex environment

Enable the Camunda SaaS environment in Qodex. See the [Qodex documentation] on managing environments for more information.

Configure the Current value of the following variables in the environment:

  • authorizationServerUrl - The URL of the authorization server. For the SaaS offering, this is https://login.cloud.camunda.io/oauth/token.

  • modelerApiAudience - The audience associated with the API client. For the SaaS offering, this is api.cloud.camunda.io.

  • modelerApiBaseUrl - The base URL of the Camunda 8 Modeler API. For the SaaS offering, this is https://modeler.camunda.io/api/v1.

  • modelerApiClientId - The client ID of the API client you created in the Camunda 8 Console.

  • modelerApiClientSecret - The client secret of the API client you created in the Camunda 8 Console.

With these values configured, a pre-request script defined on the collection will automatically retrieve an access token before each request, and store it in the modelerApiBearerToken variable. If you forget to configure any of these variables, requests will show a failed test with an error message indicating the unconfigured variable.

If you prefer to manually manage the access token, configure its value in the modelerApiBearerToken variable.

The access token is automatically included in the headers of every request in the collection: Authorization: Bearer {{modelerApiBearerToken}}.

3. Make requests to the API

With the environment configured, you can now make requests to the Camunda 8 Modeler API.

Self-Managed

For Self-Managed users:

  1. Add an M2M application in Identity.

  2. Add permissions to this application for Web Modeler API.

  3. Generate a token to access the REST API. You will need the clientid and clientsecret from the Identity application you created.
    curl --location --request POST 'http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token' \--header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=' --data-urlencode 'client_secret=' --data-urlencode 'grant_type=client_credentials'

You will get something like the following:
{ "access_token": "eyJhbG...",

"expires_in": 300,

"refresh_expires_in": 0,

"token_type": "Bearer",

"not-before-policy": 0 }

Common issues

No request made, 1/2 tests pass

If it appears no request was made, and the Test Results tab shows a failing test, there is likely misconfigured data. Common issues include:

  • No environment selected.

  • Unconfigured authorizationServerUrl, modelerApiAudience, modelerApiClientId, or modelerApiClientSecret variables.

  • Improperly formed access token.

Error message: There was an error in evaluating the Pre-request Script:Error: No data, empty input at 1:1 ^

Additional information can be found in the Qodex console. This error may indicate a problem with credentials, such as an invalid modelerApiClientId or modelerApiClientSecret.

403 Forbidden response

A 403 Forbidden response may indicate insufficient permissions for the API client. Ensure the client has the necessary scopes and permissions to perform the requested operation.

Limitations​

When using Web Modeler API:

  • You will not receive a warning when deleting a file, a folder, or a project. This is important, because deletion cannot be undone.

  • You will not receive a warning about breaking call activity links or business rule task links when moving files or folders to another project. Breaking these links is considered harmless. The broken links can be manually removed or restored in Web Modeler. This operation is also reversible - simply move the files or folders back to their original location.

Rate Limiting​

In SaaS, the Web Modeler API uses rate limiting to control traffic. The limit is 240 requests per minute. Surpassing this limit will result into a HTTP 429 Too Many Requests response.

On Self-Managed instances no limits are enforced.

FAQ​

What is the difference between simplePath and canonicalPath?​

In Web Modeler you can have multiple files with the same name, multiple folders with the same name, and even multiple projects with the same name. Internally, duplicate names are disambiguated by unique ids.

The API gives you access to the names, as well as the ids. For example, when requesting a file you will get the following information:

  • simplePath contains the human-readable path. This path may be ambiguous or may have ambiguous elements (e.g. folders) in it.

  • canonicalPath contains the unique path. It is a list of PathElementDto objects which contain the id and the name of the element.

Internally, the ids are what matters. You can rename files or move files between folders and projects and the id will stay the same.

How do I migrate from the beta API to the v1 API?​

To migrate, change the base URL from /api/beta to /api/v1.

BREAKING CHANGES

  • GET /api/beta/projects/{projectId}/files was removed. Use POST /api/v1/files/search instead.

  • GET /api/beta/files/{fileId}/milestones was removed. Use POST /api/v1/milestones/search instead.

  • GET /api/beta/projects was removed. Use POST /api/v1/projects/search instead.

Refer to the OpenAPI documentation for details.