Improve the documentation on how throttling works

[Menuka-Senevirathne]

Description:

The behavior of the throttling can differ when it comes to real life situations. Let’s consider a scenario in which we have configured 10 requests per minute. While invoking the API, the request limit might pass the 10 request margin and go up to a higher number (maximum of 20 requests) without throttling.

What actually happens here is the wso2 APIM takes the decision with regards to the actual clock time, not calculating the time since the API was invoked. Consider a scenario in which the API was invoked at the 30th second of the 1st minute, so it can cater up to 10 requests since the minute is not over yet, let’s say it caters 6 requests. Then in the 60th second,(ie in the beginning of the second minute) APIM resets the current requests and starts counting from the 0 which again can go up to 10.Then after the 10th request APIM will be throttled out. But the accumulated value is around 16 requests now. Even though it feels like a minute subjective to the user, it has taken place within two minutes in clock.

It would be better to update the official documentation with more details on this.

Affected Product Version:
All the APIM versions

[HeshanSudarshana]

Closing since the PRs are merged.