Rate limiting and thresholds
Rate limits determine how frequently you can call a particular endpoint. Usually companies have different tiers (for example, free versus pro) and licenses (open-source, business, commercial) corresponding to different capabilities or rate limits with the API.
What to cover with rate limiting
Companies with APIs make money by charging for access to the API, but they usually distinguish between low usage and high usage, often making the low usage options free so that users can explore and play with the API. With the sample OpenWeatherMap Weather API that we’ve been using in this course, you can see where the pricing begins:
If your site has hundreds of thousands of visitors a day, and each page reload calls an API endpoint, you want to be sure the API can support that kind of traffic.
This kind of information is probably within the domain of marketing rather than tech docs. However, developers will still want to know a few key behaviors around the threshold:
When you exceed the threshold, do your calls get throttled with slower responses, do you get overcharges for every extra call, or do the responses simply return a particular status code (if so, which one)?
Also, when developers implement the code into their applications or web pages, does their code handle responses that don’t provide data (due to the threshold being exceeded)? Are there conditions and checks to handle these scenarios, or does the widget (or whatever) simply freeze or hang, display empty or crash?
Examples rate limiting sections
Here are a few examples of rate limiting sections in documentation:
GitHub’s documentation explains rate limits for authenticated versus unauthenticated requests, the header returned and the meaning of the rate limiting titles (
X-RateLimit-Reset), how to check your current usage, increasing the rate limit for a specific application, what happens when rate limits are abused, and more.
Here’s a great example of the rate limits section from the Github API:
Linkedin’s rate limiting documentation explains that different API endpoints have different limits. There are three different types of throttling: Application throttling, User throttling, and Developer throttling. Their documentation also explains the time zone used to track the day’s beginning and end.
Bitly provides basic information on the page above but also links to best practices for avoid rate limiting issues. These best practices include tips such as caching, security issues, long page loads, batch processing, high-volume requests, URL encoding, and more.
By looking at these three examples, you can see that while rate limiting might seem like a simple, straightforward topic, there are many layers of depth and complexity to cover. Obviously, the relevance of the topic depends on your API and the rate limiting policies your company sets, but this information cannot simply be relegated to Marketing to handle. So much of the information around rate limiting directly affects development.
41/101 pages complete. Only 60 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.