API Throttling

Since codebeamer version Emma (21.09) a feature called "API Throttling" is enabled by default on the codebeamer server. In order to work properly with LemonTree.Connect codebeamer, version 2.4.0 or higher has to be used.

What is API Throttling?

API Throttling controls how many API requests the server handles for one client in a specific time frame. For example, the default API Throttling for codebeamer is set to 3 requests per second and a total of 20 request per minute. If more requests are sent to the server than allowed, codebeamer returns an error and a timespan how long the client has to wait before sending the next request.

Please refer to the official documentation of Intland: API Throttling

Compatibility with older LemonTree.Connect versions

If a LemonTree.Connect version lower than 2.4.x is used, all interactions with codebeamer (import, export, mapping configuration) will fail. Codebeamer releases after version "Emma" (21.09) only work with LemonTree.Connect version 2.4.x or higher. The error which will occur with incompatible versions is documented here:

Disable or Configure the API Throttling

If you use codebeamer version Emma, the API Throttling will be enabled by default. This can have a negative impact on the performance, since LemonTree.Connect codebeamer might have to attempt some API calls multiple times with delay between each attempt.

To disable the API Throttling, navigate to the Application Configuration page of codebeamer (Start > System Admin > Application Configuration).
Add a new section to the configuration:

Disable API Throttling

{
  "apiThrottling" : false
}

If you only want to configure a more lightweight throttling for certain user groups / projects or trackers, you can add a specific throttling:

Configure API Throttling

"apiThrottling": [
    {
      "groups": "<ID of user groups contains users>"
      "urlPatterns": "/project/**",
      "bandwidthConfigs": [{ "capacity": 1000, "timeUnit": "MINUTE"}]
    },
    {
      "urlPatterns": "/project/test/**",
      "bandwidthConfigs": [{ "capacity": 1000, "timeUnit": "MINUTE"}]
    }
  ]

For a more detailed explanation of the configuration capabilities, please refer to the official documentation of Intland: Official API Throttling Documentation

Performance Impact for LemonTree.Connect codebeamer

Performance tests with LemonTree.Connect release 2.4.0 were made to document the potential performance impact of the API throttling. The results are as follows.

Import of 100 elements

No noticable impact through API throttling.

Export of 100 elements

This is where the impact of the API throttling is noticable.

During this export, the API throttling is hit 41 times. In total, the export takes about 90 seconds.

For comparison: Re-running the same export with API throttling deactivated, it takes 14 seconds.