API Throttling

Default value

By default API throttling is activated with the following configuration:

  "apiThrottling": [
    {
      "urlPatterns": "/rest/**, /api/**",
      "bandwidthConfigs": [
        { "capacity": 3, "timeUnit": "SECOND"},
        { "capacity": 120, "timeUnit": "MINUTE"}
      ]
    }
  ]

Please note the API calls from word export and RPE server are not blocked by API throttling.

How to disable API throttling

In codebeamer, the API throttling can be disabled in two ways:

1. Through Application configuration, in the System Admin ► Application Configuration menu, by adding the below line to the main JSON object:

"apiThrottling" : false

2. By setting the CB_apiThrottling=false environment variable. For more information, see Application configuration via environment variables.

How to set up API throttling

API throttling configuration must be added to the Application Configuration as a new JSON node. Upon saving the configuration 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.

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"},
        ...
      ]
    }
  ]

URL Patterns

Comma separated Ant path style patterns. Please note that 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' (e.g. 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 please refer to the official java documentation: Java Regex

Day of week

Comma separated values

Possible values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY

Group IDs

Comma separated values of ID of user groups

You can use the following SQL query in order to find the ID for a group

select name, id from user_group order by name

User IDs

Comma separated values of ID of users

You can use the following SQL queries in order to find the ID for a user

Find user by name:

select id from users where name = '<name>';

Find user by email address:

select id from users where email = '<email>';

Synchronized lock

True (default value)

Blocking strategy based on java <code>synchronized</code> keyword.

• Advantages: Never allocates memory.
• Disadvantages: Thread which acquired the lock(and superseded from CPU by OS scheduler) can block another threads for significant time.
• Usage recommendations: when your primary goal is avoiding of memory allocation and you do not care about contention.

False

Lock-free algorithm based on CAS(compare and swap) of immutable objects.

• Advantages: This strategy is tolerant to high contention usage scenario, threads do not block each other.
• Disadvantages: The sequence "read-clone-update-save" needs to allocate one object per each invocation of consumption method.
• Usage recommendations: when you are not sure what kind of strategy is better for you.

Time windows configuration

A list of timeWindows objects. A time window object has a from and a to parameter, determining the time period when API throttling is in effect. The following validation rules apply to timeWindows objects:

• Timestamps have to be 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, determining the beginning of the time window.

To

A 24-hour timestamp in HH:mm format, determining the end of the time window.

Examples

Example 1

This configuration is in effect on Mondays, between 9:00-11:00 and 14:00-17:00:

"apiThrottling": [
    {
      "urlPatterns": "/project/*,/user/*",
      "days": "MONDAY",
      "groups": "3,4",
      "users": "1,2",
      "synchronizedLock" : true,
      "timeWindows" : [
        { "from" : "09:00",
          "to": "11:00"
        },
        { "from" : "14:00",
          "to": "17:00"
        }
      ],
      "bandwidthConfigs": [
        {
          "capacity": 100,
          "timeUnit": "MINUTE"
        }
      ]
    }
]

Example 2

This configuration fails on validation, as there are overlapping time windows:

"apiThrottling": [
    {
      "urlPatterns": "/project/*,/user/*",
      "days": "MONDAY",
      "groups": "3,4",
      "users": "1,2",
      "synchronizedLock" : true,
      "timeWindows" : [
        { "from" : "09:00",
          "to": "16:00"
        },
        { "from" : "09:00",
          "to": "11:00"
        }
      ],
      "bandwidthConfigs": [
        {
          "capacity": 10,
          "timeUnit": "DAY"
        }
      ]
    }
]

Bandwidth configuration

Time unit

Possible values: DAY, HOUR, MINUTE, SECOND

Capacity

Positive number

It is a number of call that can happen during the given time unit.

Example

Capacity is set to 5, time unit is MINUTE. It means that only 5 calls can happen in every minute. Please note the start and end of a minute is not bound to the server clock. In other words 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 from the parameters (day, users, groups) is set the precedence is 1, if two then the precedence is 2, and so on. Always the rule with the highest precedence number are found and executed.

Example 1

  "apiThrottling": [
    {
      "urlPatterns": "/project/**",
      "bandwidthConfigs": [{ "capacity": 5, "timeUnit": "MINUTE"}]
    },
    {
      "urlPatterns": "/project/test/**",
      "bandwidthConfigs": [{ "capacity": 10, "timeUnit": "MINUTE"}]
    }
  ]

Let's say that user one calls /project/test/example.spr 5 times and user two tries to call the /project/test2/example.spr but he 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"}]
    }
  ]

Let's say that user one calls /project/test/example.spr 5 times and user two tries to call the /project/test2/example.spr, user two can call the /project/test2/example.spr.

It happens because the first rule has a higher precedence and it is only applied for user one, 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 that in 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 that in the previous example, the first rule is not applied

On Sunday

Let's say that user one 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. User two is able to 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

Let's say that user one 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.

User two is able to 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 with the following

  "apiThrottling": [
    {
      "users": "<ID of user one>",
      "urlPatterns": "/**",
      "bandwidthConfigs": [{ "capacity": 1, "timeUnit": "MINUTE"}]
    },
    {
      "urlPatterns": "/**",
      "bandwidthConfigs": [{ "capacity": 5, "timeUnit": "MINUTE"}]
    }
  ]

TOO_MANY_REQUESTS

Codebeamer returns a TOO_MANY_REQUESTS (429) error code and a Retry-After header

Swagger changes

Swagger API changes since 20.11-LTS

REST API

REST API Changes - 20.11-LTS