The API is rate limited to protect against overload situations.
Rate limiting on the API is designed to protect the platform from excessive requests. When the number of request received within a time window reaches a threshold number, then further requests are rejected until the rate falls back below that threshold. Also there is a maximum size of query response that can be selected using the .maxResults query parameter. Also the maximum number of concurrent requests (per user and across all users) that the server will handle can be configured. Once this limit is reached further requests will be rejected. There are five thresholds that can be set by the system administrator of the platform:
If any of these thresholds is exceeded, then requests will be rejected with status code of 503 (Service Unavailable). The text of the response will contain information about the cause as appropriate:
In the case of the per user threshold being exceeded, other users will continue to have access to the NBI as normal.
Note that requests rejected by the rate limiter do not count in calculation of the threshold. Requests that fail due to other factors are still counted.
The Rate Limits Management Service provides resources to get and update current rate limits. Rate limits affect all users and take effect immediately after updating. A platform restart is not required.
Rate limiting properties ares saved in a file named nbi.properties and placed in the directory /opt/CSCOlumos/conf/. The properties are defined in the table below. Note that it is not recommended to change the file manually. It can only be changed by a systems administrator, and will require a platform restart to take effect.
Property | Allowed Values | Default Value | Description |
---|---|---|---|
nbi.rateLimit.windowSize | An integer representing a number of milliseconds. | 1000 | This property is the size of the sliding window used to count requests. |
nbi.rateLimit.windowSegments | A integer value such that windowSize/windowSegements is a whole number. | 10 | This property is used internally to divide the window into segments. The number of segments determine the rate at which the window decrements the request counter. For example with 10 segments in a 1000 ms window, the count will be reduced every hundred ms, by the number of counts held in the oldest segment. (The count is increased immediately after receiving a new request). |
nbi.rateLimit.totalRequestThreshold | An integer. Use -1 to disable the limiting of total requests. | 20 | This is the number of total request that can be handled in windowsize ms. |
nbi.rateLimit.perUserThreshold | An integer. Use -1 to disable the limiting of per user requests. | 5 | This is the number of requests for any given user that can be handled in windowsize ms. |
nbi.rateLimit.maxConcurrentQueries | A non-zero positive integer. | 10 | This is the number of concurrent requests allowed for any given user. |
nbi.rateLimit.maxAllUserConcurrentQueries | A non-zero positive integer. Use -1 to disable the limiting of all user concurrent requests | 45 | This is the number of concurrent requests allowed for all users. |
nbi.rateLimit.limitPageSize | A non-zero positive integer. | 1000 | This is the maximum size of a page that the user can request through .maxResults query parameter. |
nbi.rateLimit.limitUnpagedQuery | A non-zero positive integer. | 100 | This is the default size of a page returned when .maxResults query parameter is not specified. |
There is only one rate limiting parameter for operational resources: number of concurrent requests allowed for all users. When the number of concurrent requests reaches the configured number, then further requests are rejected with status code of 503.
Rate limits for operations are configured individually for each resource and cannot be changed by users. Whether rate limiting is enabled or not for a particular resource can be found on the resource's documentation page.
There are two rate limiting threshold for Server-Sent Events resources:
If any of these thresholds is exceeded, then requests will be rejected with status code of 503 (Service Unavailable). The text of the response will contain information about the cause as appropriate:
SSE rate limiting properties ares saved in a file named nbi.properties and placed in the directory /opt/CSCOlumos/conf/. The properties are defined in the table below. Note that it is not recommended to change the file manually. It can only be changed by a systems administrator, and will require a platform restart to take effect.
Property | Allowed Values | Default Value | Description |
---|---|---|---|
nbi.sseRateLimit.maxAllUserSseSubscriptions | An integer. Use -1 to disable the limiting of total requests. | 100 | This is the number of concurrent requests allowed for all users. |
nbi.sseRateLimit.perUserSseSubscriptions | An integer. Use -1 to disable the limiting of per user requests. | 20 | This is the number of concurrent requests allowed for any given user. |