Originally Published October 25, 2019
Based on feedback from our recently published API Rate Logging announcement here is a follow-up article contains a series of questions we have commonly received from customers and partners. Note that as we receive more questions and more answers, we will be updating the contents of this article.
Q. At what level will API Rate Limiting be applied? Is it per instance? Per Org? Per API App?
A. We will be applying API Rate Limiting at the API App level. For clarity, an API App relates to each App that is created and maintained within a Brightspace Org's Manage Extensibility Tool. Each Manage Extensibility App enabled in a Brightspace site will be allocated its own siloed bucket of API credits.
Q. What will the API Rate Limit Bucket Size be?
A. The Rate Limit Bucket Size is 50,000 API Credits per minute. Please note that we include the following in every API Response Header:
X-Rate-Limit-Remaining - this value provides a developer with the remaining number of credits available within the provided time-frame. NOTE: this value will only be meaningful on sites where API Rate Limiting is turned ON.
Q. Will you be publishing the token costs per API route?
A. As of December 3rd, 2019 the route token costs are set at 10 credits per API call.
As we monitor and analyze API usage logs we will be able to better understand the actual server costs of our API routes. The outcome of this is that we want to reserve the right to change API route token costs. We fully anticipate API Route costs are going to change prior to the full product launch in May 2020.
We include the following in every API Response Header:
X-Request-Cost - this value informs the developer of the number of credits the current API route cost. At this time, this value will always be 10.
Q. Will there be any way to know if one of my Apps has exceeded the API Rate Limit (a 429 message)?
A. Yes. This data will be available through the Brightspace System Log. This data will be retained in the System Log based on current data retention rules. Search for "Route hit a rate limit" to find Rate Limit events (429 messages).
Q. Will there be any way to know if one of my Apps has triggered an API Rate Log?
A. Yes. Starting in our December product release, this data will be available through the Brightspace System Log. This data will be retained in the System Log based on current data retention rules. Search for "Route hit a log limit" to find Rate Limit Log records. For systems that have API Rate Limiting turned ON search your System Log for "Route hit an excess limit" to identify Rate Limit events (429 errors).
Q. Will API Rate Limiting include calls to LTI Services?
A. Yes. All LTI Advantage service calls are subject to the same rate limiting as our Brightspace Learning Framework APIs.
Q. Will there be any indicators available to inform a developer that they are getting close to using up their API Rate Limit Bucket?
A. Yes. The X-Rate-Limit-Remaining value informs a developer on how many credits they have remaining to use within the current minute time-frame.
Q. Will there be a way to know how much time is left until my API credit bucket is refilled?
A. Yes. We include the following field in our response header:
X-Rate-Limit-Reset - this value provides a developer with the amount of time, in seconds, until their bucket resets.
Q. I just received a 429 message. How will I know how long I have to wait until my API credit bucket is refilled?
A. For 429 responses, we include an industry-standard header response value:
Retry-After - this value provides a developer with the amount of time, in seconds, until their bucket resets.
Q. Will it be possible to purchase extra credits or a larger credit bucket?
A. No. We believe that the amount of credits available per minute reflects an acceptable use amount.
Q. I am concerned that my App will exceed the provided limits and my code is not ready to handle 429 messages. What can I do?
A. With our initial announcement occurring in October of 2019 we at D2L believe that we have provided a significant amount of preparation time for customers. We encourage all customers to work with your D2L TAM and/or CSM to prepare for this change. We at D2L are more than happy to engage with you on how API Rate Limiting may impact the existing code you have written.
Our goal for this initiative is to maintain the performance and stability of your Brightspace investment. We have built the solution in such a way that we can manage exemptions where needed, but we want to avoid granting these exceptions as much as possible. If you believe you require an exemption please reach out to your D2L CSM and/or TAM so we can work together to decide on a mutually agreeable path forward.
Q. Do unsuccessful API calls (e.g. 400, 403, 404) cost my App credits?
A. Yes. Rate Limiting logic occurs prior to us processing the API call. At the point in time when we receive the call, we don't know if it will be successful or not.