StatPro Revolution Web API
Fair Usage Policy
- Request limitation
- Exceptional cases
- Detecting blockage
- Viewing Fair Usage statistics
To maintain optimum performance, and to ensure that the StatPro Revolution Web API is available to all our customers, limits are imposed on the usage of the Web API.
Applications should be written so as to not violate the policy. Applications must be able to detect when access to the Web API has been blocked because of policy violations.
The following outlines the limit for the total number of Web API requests per rolling 24-hour period for a tenancy, within each registered client application:-
2,000 x number of "Platinum Portfolios" purchased +
1,000 x number of "Gold Portfolios" purchased +
500 x number of "Silver Portfolios" purchased +
200 x number of "Bronze Portfolios" purchased.
(For details about Platinum, Gold, Silver and Bronze Portfolios, please contact StatPro.)
The limit is enforced against the aggregate of all API calls made on behalf of a tenancy by a client application, in a rolling 24-hour period (since many users can use the same application).
To be clear: the limit applies to the combination of a particular tenancy and a particular client application.
In most cases, a request for a resource is counted as just that: one request. In exceptional cases, where a request may cause a very large amount of data extraction and processing to be performed on the server, a request may be counted as more than one request (with respect to the Fair Usage Policy).
The following resources are exceptional in that requests for them may be counted as more than one request; please see their linked-to documentation for details:-
When the limit is exceeded, all users in the tenancy may be temporarily blocked from making additional calls from the client application. Calls may be blocked until usage for the preceding 24 hours drops below the limit. Re-checking to see if calls are allowed again is performed every 10 minutes.
Using a concrete example:-
Users in tenancy T are using client application A. The tenancy has 1 (one) Gold portfolio, 1 (one) Silver portfolio and 2 (two) Bronze portfolios. Thus the total number of calls allowed in a 24-hour period is (1 * 1000) + (1 * 500) + (2 * 200) = 1900.
Starting at 09:00 and continuing until 21:00, 1901 calls are made by A on behalf of users in T. Assuming no previous usage of the app (and thus no prior blocking), the first 1900 calls are not blocked. Call number 1901 is blocked. Subsequent calls are also blocked. Every 10 minutes or so, as calls come in, a check is made to see if the limit has not been exceeded for the preceding 24-hour period. Finally, at 09:00 on the next day (or soon after), the limit for the preceding 24 hours is found not to have been exceeded, and a further call is allowed (and so on).
In addition to the above rolling 24-hour limit, if a considerable portion of the tenancy's limit is used in any 5 minute period, throttling may be applied to slow down the responsiveness of further API requests. This serves to protect the Revolution system from accidental overload or Denial-of-Service (DoS) attack.
Requests may be throttled until usage for the preceding 5 minutes drops below the throttling threshold. The threshold is set to a value within the range of 5,000 to 20,000 requests (depending on the number of portfolios purchased).
If a client application is blocked (as opposed to throttled) as described above, the requests that it makes during the blockage period will fail with HTTP response status 403 (Forbidden). The reason phrase on the status line of the response will be:-
The request is forbidden because the combination of the requesting client application and the user's tenancy has been blacklisted due to usage exceeding the Revolution Web API's Fair Usage Policy limits. Please refer to the Fair Usage Policy section in the Web API documentation for more details. (REVAPI_ERROR=852)
For more information on the Web API's error codes and messages, please see Appendix 1 - Error Codes.
Purchasing extra portfolios (or credits) for the tenancy in question is obviously an effective way to unblock a client application. However, the Fair Usage Policy (FUP) implementation does not automatically notice that extra credits have been purchased. Instead, the credits count is conveyed to the FUP implementation via the Bearer access token that the client application obtains from the Revolution OAuth2 Server, and presents to the Web API for each and every request.
For this reason, an increase in credits is only noticed when existing access tokens are discarded (or expire), and new ones obtained. If a client application is blocked, but more credits have been (or may have been) purchased for the user's tenancy, the user should be prompted to log out of / log back in to the app, in order to pick up the latest credits count.
Viewing Fair Usage statistics
The StatPro Revolution API Authorization Management website allows end users to view the Fair Usage statistics for the client application and the tenancy that are associated with any one of their outstanding authorizations. This allows users to determine if the application + tenancy combination is currently blacklisted or throttled, how close it is to being blacklisted, etc.
Last updated: December 2016