What variables are in the API Response Header?
For all Brightspace API Apps (that are not currently on our API Rate Limiting SafeList) every Brightspace API Response 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. Every minute, this value gets reset back to the full bucket size. Each API call within the current minute will decrease this value by X-Request-Cost.
X-Rate-Limit-Reset - provides the developer with the amount of time, in seconds, until their bucket resets. This value is controlled by the Brightspace server’s clock.
X-Request-Cost - informs the developer of the number of credits the current API route cost. For now, this value will always be set to 10.
The Header Values aren’t there when I get a 429. Help!
If the Brightspace API is called, and a 429: Too Many Requests response is returned, the API Response Header values returned differ from other response values. We decided to align our 429 response with the internet standard. Therefore, we include a different, yet standard, value in all 429 responses:
Retry-After - provides the developer with the amount of time, in seconds, until their bucket resets and they can once again successfully perform Brightspace API calls.
How can I see the Response Headers?
The easiest way to “see” these response header variables is through Postman. Within Postman, perform a Brightspace API request (for example, our WhoAmI route). Typically in Postman, after you send a Request your default view will show you the API Response Body. To see the API Response Headers just click on “Headers”.
Why am I not seeing them?
There may be a few reasons why you still cannot see these API Response Header values:
- You are using the API Test Tool. The API Test Tool is a great resource for developers. But, it uses a PHP “wrapper” interface to send API Requests and to receive API Responses. A resourceful developer can create their own API Test Tool and add Header Response values to it if they would like. If you do please let us know!
- You are using a Brightspace API App that is on our Rate Limiting SafeList. These Apps do not have API Rate Limiting enforced and therefore these response values are not necessary.
- Within Postman, you may have your Brightspace cookies Cached which may override the Bearer token. In this scenario, we may not include the Rate Limiting Response Header values. Just delete your Cookies in Postman and ensure that you are including the OAuth 2.0 Access Token as a Bearer Token in your API request header.