Rate Limit
Our APIs are a shared resource, intended to be highly available as a general-purpose tool that can be called upon at any time. As such, we enable rate limiting as is standard practice. The rate limitations may be adjusted at any time without warning, in order to ensure reliability.
The rate limit is applied per IP and accumulated regardless of endpoint. This means that if you download from the
/classesendpoint, and then start downloading at /students endpoint, the quota is accumulated for each call to each endpoint, by IP address.Any application ingesting data from these APIs should take the following precautions to be able to respond to any changes in rate limitations:
-
A http response of
429means that the rate limit has been exceeded. Clients may use the response headers to determine how long to wait until trying again. See table below.
-
Use the
per_pagequery parameter to set it to a reasonable value, such as50. Please note that the API may return a number of records less than passed in the request. The application code can use themetaobject to determine how many records are being returned per request.
429 Headers
When a
429 response is returned, clients may use the headers to re-try. The current rate limit can be calculated via X-RateLimit-Limit divided by X-RateLimit-Period. The below example shows the values for a rate limite of 50 requests per second (per IP):| Header Name | Description | Example |
| X-RateLimit-Limit | The number of requests that can be sent in the period indicated by X-RateLimit-Period |
50 |
| X-RateLimit-Period | The denominator of the rate limit, in seconds | 1 |
| X-RateLimit-Reset | The time when a request can be re-tried. |
2021-10-28 01:29:40 UTC |
Best Practices
In order to ensure high availability, schools can consider the following to mitigate potential for throttling:
-
In consultations with schools, there is general consensus that overnight processes are adequate in most use cases. If refreshes are needed more often, it is rarely necessary to conduct updates more often than once an hour.
-
Use polling to repeatedly ask a particular endpoint for updates. By utilizing the
modified_sinceparameter whose value is set to the YYY-mm-dd time when last queried. With this method, your client application can retrieve iterative updates, ensuring that only the records which have been updated since that date passed are returned, rather than "all" the records. This results in more performant code and uses far fewer server resources.
-
The following endpoints support polling on GET requests:
/students,/parents,/teachers,/year-groups, and/membershipendpoints.