API Throttling
Default value
API throttling is activated with the following configuration by default:
"apiThrottling": [
{
"urlPatterns": "/rest/**, /api/**",
"bandwidthConfigs": [
{
"capacity": 3,
"timeUnit": "SECOND"
},
{
"capacity": 120,
"timeUnit": "MINUTE"
}
]
},
{
"urlPatterns": "/createUser.spr",
"bandwidthConfigs": {
"capacity": 100,
"timeUnit": "MINUTE"
}
}
],
API throttling does not block API calls for OSLC, word export, or RPE server.
How to disable API throttling
In Codebeamer, the API throttling can be disabled in two ways:
• In Application configuration, click > menu and add the following line to the main JSON object:
"apiThrottling" : false,
• Set the CB_apiThrottling=false environment variable. For more information, see Application configuration via environment variables.
 |
The CB_apiThrottling=false environment variable takes precedence over any other "apiThrottling" application configurations.
|
How to set up API throttling
API throttling configuration must be added to the Application Configuration as a new JSON node. When the configuration is saved, the system runs a validation against the following rules:
• bandwidthConfig is missing.
• In timeWindows configuration the to parameter is before the from parameter.
• In timeWindows configuration there are overlapping time windows.
 | If the validation fails against any of the rules, an error message is displayed, and the Application Configuration setting are not saved. |
Format
"apiThrottling": [
{
"urlPatterns": "[URL PATTERN, URL PATTERN...]",
"serverIds": "[SERVER ID PATTERN, SERVER ID PATTERN...]",
"days": "[DAY OF WEEK]",
"groups": "[USER GROUP ID, USER GROUP ID...]",
"users": "[USER ID, USER ID...]",
"synchronizedLock": true / false,
"timeWindows" : [
{ "from" : "HH:mm",
"to" : "HH:mm"
},
{ "from" : "HH:mm",
"to" : "HH:mm"
},
...
],
"bandwidthConfigs": [
{ "capacity": CAPACITY, "timeUnit": "TIMEUNIT"},
{ "capacity": CAPACITY, "timeUnit": "TIMEUNIT"},
...
]
}
]
Parameter | Description | ||
|---|---|---|---|
URL Patterns | Comma separated Ant path style patterns. The context path is not part of the pattern. The mapping matches URLs using the following rules: • ? matches one character. • * matches zero or more characters. • ** matches zero or more directories in a path. Examples ◦ com/t?st.jsp — matches com/test.jsp but also com/tast.jsp or com/txst.jsp. ◦ com/*.jsp — matches all .jsp files in the com directory. ◦ com/**/test.jsp — matches all test.jsp files underneath the com path. ◦ org/springframework/**/*.jsp — matches all .jsp files underneath the org/springframework path. ◦ com/**/servlet/bla.jsp — matches com/Codebeamer/servlet/bla.jsp but also com/Codebeamer/testing/servlet/bla.jsp and org/servlet/bla.jsp. ◦ com/{filename:\\w+}.jsp will match com/test.jsp and assign the value test to the filename variable. | ||
Server Ids | Comma separated JAVA regex patterns. Examples ◦ srv.* —matches all servers starting with the name srv. For example srv-1, srv-2. ◦ win-\\d*-srv —matches all servers starting with the name win and ending with srv, between the two any number of digits allowed (e.g. win-01-srv, win-3-srv). For more details, see the official Java documentation on Java Regex. | ||
Day of week | These are comma separated values. Possible values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY. | ||
Group IDs | These are comma separated values of user groups IDs. Use the following SQL query to find the ID for a group: • select name • id from user_group order by name | ||
User IDs | These are comma separated values of users IDs. Use the following SQL queries to find the ID for a user. • Find user by name: select id from users where name = '<name>'; • Find user by e-mail address: select id from users where email = '<email>'; | ||
Synchronized lock | The values are as follows True (default) Blocking strategy based on Java <code>synchronized</code> keyword. ◦ Advantages: Never allocates memory. ◦ Disadvantages: The thread which acquired the lock and which is superseded from CPU by OS scheduler can block other threads for significant time. ◦ Usage recommendations: When your primary goal is avoiding memory allocation, and you want to ignore contention. False Lock-free algorithm based on Compare And Swap (CAS) of immutable objects. ◦ Advantages: This strategy is tolerant to high contention usage scenario. The threads do not block each other. ◦ Disadvantages: The read-clone-update-save sequence, allocates one object per each invocation of consumption method. ◦ Usage recommendations: When you are unsure about a better strategy. | ||
Time windows configuration | This is a list of timeWindows objects. A time window object has a from and a to parameter, which determine the time period when API throttling is in effect. The following validation rules apply to timeWindows objects: • Timestamps are recorded in a 24 hour format: HH:mm. • Valid values for hours. • Valid values for minutes. • The from parameter must precede the to parameter. • If multiple time windows are configured, they cannot overlap.
From A 24-hour timestamp in HH:mm format that, determines the beginning of the time window. To A 24-hour timestamp in HH:mm format that, determines the end of the time window. Examples Example 1 The following configuration is in effect on Mondays, between 9:00-11:00 and 14:00-17:00. "apiThrottling": [ Example 2 The following configuration fails on validation, as there are overlapping time windows. "apiThrottling": [ | ||
Bandwidth configuration | Time unit The possible values are DAY, HOUR, MINUTE, SECOND. Capacity It is a positive number. It is the number of calls that can happen during the specified time unit. Example If capacity is set to 5, time unit is MINUTE, it implies that only 5 calls can happen in every minute. The start and end of a minute is not bound to the server clock. If the configuration is applied at 12h 00m and 30 seconds, 5 calls can happen between 12:00:30 and 12:01:30. |
Precedence of configuration - examples
Precedence of rules depends on the number of parameters are set.
If only one parameter from day, users, or groups parameter is set the precedence is 1. If two parameters are set, the precedence is 2, and so on. Always the rule with the highest precedence number is found and executed.
Example 1
"apiThrottling": [
{
"urlPatterns": "/project/**",
"bandwidthConfigs": [{ "capacity": 5, "timeUnit": "MINUTE"}]
},
{
"urlPatterns": "/project/test/**",
"bandwidthConfigs": [{ "capacity": 10, "timeUnit": "MINUTE"}]
}
]
If User1 calls /project/test/example.spr five times and User2 tries to call the /project/test2/example.spr but the User2 will receive a TOO_MANY_REQUESTS (429) error.
Example 2
"apiThrottling": [
{
"users": "<ID of user one>"
"urlPatterns": "/project/**",
"bandwidthConfigs": [{ "capacity": 5, "timeUnit": "MINUTE"}]
},
{
"urlPatterns": "/project/test/**",
"bandwidthConfigs": [{ "capacity": 10, "timeUnit": "MINUTE"}]
}
]
If User1 calls /project/test/example.spr five times and User2 tries to call the /project/test2/example.spr, User2 can call the /project/test2/example.spr.
It happens because the first rule has a higher precedence and it is only applied for User1, while the second rule is applied for every user.
Example 3
"apiThrottling": [
{
"groups": "<ID of user groups contains user one>"
"urlPatterns": "/project/**",
"bandwidthConfigs": [{ "capacity": 5, "timeUnit": "MINUTE"}]
},
{
"urlPatterns": "/project/test/**",
"bandwidthConfigs": [{ "capacity": 10, "timeUnit": "MINUTE"}]
}
]
Same result according to the previous example.
Example 4
"apiThrottling": [
{
"days": "SATURDAY, SUNDAY",
"users": "<ID of user one>",
"urlPatterns": "/project/**",
"bandwidthConfigs": [{ "capacity": 1, "timeUnit": "MINUTE"}]
},
{
"users": "<ID of user one>",
"urlPatterns": "/project/test/**",
"bandwidthConfigs": [{ "capacity": 5, "timeUnit": "MINUTE"}]
}
{
"urlPatterns": "/project/test/**",
"bandwidthConfigs": [{ "capacity": 5, "timeUnit": "MINUTE"}]
}
]
◦ On Monday
Same result according to the previous example. The first rule is not applied.
◦ On Sunday
If User1 calls /project/test/example.spr 2 times, first call is served by the Codebeamer but the second call ends with TOO_MANY_REQUESTS (429) error. User2 can call /project/test2/example.spr.
Example 5
"apiThrottling": [
{
"days": "SATURDAY, SUNDAY",
"users": "<ID of user one>",
"urlPatterns": "/project/**",
"bandwidthConfigs": [{ "capacity": 1, "timeUnit": "MINUTE"}]
},
{
"days": "SUNDAY",
"groups": "<ID of user groups contains user one and user two>"
"urlPatterns": "/project/**",
"bandwidthConfigs": [{ "capacity": 5, "timeUnit": "MINUTE"}]
},
{
"urlPatterns": "/project/test/**",
"bandwidthConfigs": [{ "capacity": 5, "timeUnit": "MINUTE"}]
}
]
On Sunday
If User1 calls /project/test/example.spr 2 times, first call is served by the Codebeamer but the second call ends with TOO_MANY_REQUESTS (429) error.
User2 can call /project/test2/example.spr.
Example 6
"apiThrottling": [
{
"users": "<ID of user one>",
"bandwidthConfigs": [{ "capacity": 1, "timeUnit": "MINUTE"}]
},
{
"bandwidthConfigs": [{ "capacity": 5, "timeUnit": "MINUTE"}]
}
]
Example above is equivalent to the following.
"apiThrottling": [
{
"users": "<ID of user one>",
"urlPatterns": "/**",
"bandwidthConfigs": [{ "capacity": 1, "timeUnit": "MINUTE"}]
},
{
"urlPatterns": "/**",
"bandwidthConfigs": [{ "capacity": 5, "timeUnit": "MINUTE"}]
}
]
TOO_MANY_REQUESTS
Swagger changes