Skip to content

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 the codebeamer connector, a version 2.4.0 or higher of the connector 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: https://codebeamer.com/cb/wiki/17380873

Compatibility with older connector versions

If a codebeamer connector 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 the connector version 2.4.x or higher. The error which will occur with incompatible versions is documented here:

undhandled error

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 the connector 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 documentation

Performance Impact for the Connector

Performance tests with codebeamer connector 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.