Originally published February 10, 2020
API Rate Limit Logging has now been in place since October of 2019. Since then we have been monitoring the Rate Limit logs that have been generated. We have also spent time meeting with many customers and partners to discuss the log data. The following is a summary of how we have adapted based on what we have learned.
API Response Headers
For Brightspace sites with API Rate Limiting turned ON, every Brightspace API call now includes 3 additional pieces of data in its response header:
X-Rate-Limit-Remaining - the remaining number of credits available within the current minute.
Note: This value is only meaningful on Brightspace Sites that have API Rate Limiting turned ON
X-Rate-Limit-Reset - provides the developer with the amount of time, in seconds, until their bucket resets.
X-Request-Cost - informs the developer of the number of credits the current API route cost.
For some solutions, these header values can provide a way to avoid every exceeding the Rate Limit threshold.
Turn Rate Limiting ON for Non-Production Sites - March 9th, 2020
In order to provide everyone with access to a Brightspace environment that has Rate Limiting turned ON we are planning to do so on all Non-Production Brightspace Sites on March 9th, 2020. This will provide all customers and partners with access to a site where they can:
- Create a test scenario where they can actually exceed a Rate Limit threshold and generate a 429 error.
- Test and use the X-Rate-Limit-Remaining response header value (as this value is only meaningful on sites where API Rate Limiting is turned on).
IMPORTANT - If you do NOT want Rate Limiting turned ON for one of your non-production Brightspace sites please contact your D2L TAM and/or CSM prior to March 9th.
Turn ON Incremental Logging - March 2nd, 2020
Some feedback we have received repeatedly is that you want to know if and when your API App is getting “close” to the Rate Limiting threshold value. To accommodate this request we have added a new “incremental logging” feature to our Rate Limiting solution. Our plan is to turn ON Incremental Logging on March 2nd, 2020.
Incremental Logging will generate Rate Limit Logs when any API App uses over 30,000 credits within a minute. Additional logs will be generated when that API App exceeds any multiple of 10,000 over the initial 30,000 credit level.
For example, if an API App uses 72,000 API credits in a minute, our Incremental Logging feature will generate 5 unique logs: the first will be when the app exceeded 30,000 credits, the next being for when the app exceeded 40,000 credits, the 3rd for 50,000 credits, the 4th at 60,000 credits, and the last log for exceeding 70,000 credits.
Incremental logging provides two important data points:
- It provides us all with a means of determining which API apps are “getting close” to the 50,000 credits/minute threshold.
- For apps that are exceeding the 50,000 credit limit, incremental logging informs us of how far above the threshold the app has gone.
Turning Rate Limiting ON - Monday, June 8th, 2020
Previous to the publication of this article we had communicated that we were turning Rate Limiting ON sometime in May of 2020. Based on your feedback, we have decided to move the go-live date to Monday, June 8th, 2020 (for all Production sites). The general feedback was that May is often a busy month for the retrieval of data from Brightspace via the API.
As stated previously, if you have concerns about having API Rate Limiting turned on please inform your D2L TAM and/or CSM. Include the API App you are concerned about plus the reason you would not want Rate Limiting turned on in June.