How to throttle PRIS calls

Relates to versions - Pitram Restful Integration Service (PRIS) 1.0+

This guide has been created to assist administrators and system specialists in throttling calls made to the PRIS API.

Overview:

To ensure the frequency of calls made to the PRIS interface do not impact system performance or stability, it is necessary to limit or throttle the volume of calls, particularly where the calls relate to report requests. The limitation can be applied globally, or in a more pointed fashion to ensure sufficient access to the interface, whilst maintaining system performance.

Examples:

The following examples have been generated to provide an understanding of the functionality, as well as a starting point to define the requirements for each implementation.

Global Throttling:

The most generic method of throttling for the PRIS API involves limiting the volume of calls at a global level. This is performed by adding variables to the C:\inetpub\wwwroot\PRIS\config\throttlePolicy.config file based on requirements:

Any client machines within the 10.10.100.0 subnet will be subject to a maximum of one call per second, and 5 calls per minute. This is quite a broad restriction, disallowing all IP addresses unless the fall into the whitelist category.

In the following example, we limit the API calls from IP Addresses 10.10.10.10 and 10.10.10.1 to allow execution once per minute, along with the existing IP Range above:

This is useful in a scenario where an API Client has been configured to create excessive calls against the PRIS service, and there is no ability to tune the calls. Applying the throttling configuration above would simply drop all request for 60 seconds after a call from the API Client is made. This doesn't afford any selective call processing, but can be tuned based on the following variables:

limitPerSecond="1"
limitPerMinute="10"
limitPerHour="30"
limitPerDay="300"
limitPerWeek ="1500"

The variable at the end of each line can be set as desired, however will function without any smarts. For example, if the variable 'limitPerHour' is set to 30, and calls are made every two seconds, the throttling will process the call for 60 seconds, and then each call will be dropped until the hour time limit is exceeded, and the calls will be allowed to execute again.

Client Throttling:

It is possible to further limit the quantity of queries based on client keys. In this way, an administrator could limit calls made from a third party reporting system, whilst still allowing their weighbridge to add data without making it submit to the same limitations.

This example shows a limit of 60 calls for the API Key "aCELgL. 0imfnc8mVLWwsAawjYr4Rx-Af50DDqtlx" Assuming this is our third party reporting solution, it will be limited to 60 calls per hour. In this way, it is filtered regardless of IP address (Unless the IP address exists in the scope above) and potentially across multiple sources.

Endpoint Throttling:

Endpoint throttling allows an administrator to limit the number of calls being made for specific functions within PRIS. For example, one could throttle the Equipment Measures report:

As can be seen in the <!--Endpoint rules--> section, we are limiting the report execution to just 6 calls per hour. This will allow the system to retain performance without creating excessive report queries. Each endpoint can be defined according to requirements, and a list of available endpoints can be found in the PRIS Swagger form (http://HostNameorIPAddress/PRIS)

Whitelisting:

As can be seen above, any of the methods of throttling allow the ability to significantly reduce the calls made against the PRIS API. With that in mind, and armed with the understanding that the throttlePolicy does not function dynamically, it might be found that exclusions need to be made. For example, the weighbridge mentioned earlier, Should that function be seen as production critical it would be prudent to list the device on a whitelist to ensure it is never impacted by the throttlePolicy.

This example shows how any of the three methods of throttling can be over-ridden. Either by stipulating the IP Address of the Weighbridge, the Client Key, or the Endpoint. Each has its own merit, and may be used in combination with others to ensure the correct level of restriction is applied.

Conclusion:

Using throttling will allow refinement of the calls being made against the PRIS service, providing stability by reducing unwarranted calls being made and ensuring a system can be protected should a malformed call be produced that is unable to be managed quickly or effectively.

Want to learn more?

Click here to login to our Learning Management System

Click here to request access