Rate limiting your RESTful API
Seventh article in the series of “ Pragmatic decisions for your RESTful API”, this post talks about rate limiting for your RESTful API.
Rate limiting: use X-RateLimit-* HTTP headers and 429 status code
Rate limiting becomes necessary when your API starts becoming used by a wide range of applications and users.
When a rate limit is reached, your API should return the following HTTP status code:
429 Too Many Requests
Unfortunately however, there is no standard name for the HTTP headers you can use to inform users of the rate limits:
Twitter uses the following headers:
X-Rate-Limit-Limit: the rate limit ceiling for that given endpoint
X-Rate-Limit-Remaining: the number of requests left for the 15 minute window
X-Rate-Limit-Reset: the remaining window before the rate limit resets, in UTC epoch seconds
Github uses the following headers:
X-RateLimit-Limit: The maximum number of requests you're permitted to make per hour.
X-RateLimit-Remaining: The number of requests remaining in the current rate limit window.
X-RateLimit-Reset: the time at which the current rate limit window resets in UTC epoch seconds
There seems to be, however, more RESTful API frameworks using Github’s standards than Twitter’s standards, which is why I advise you to use Github’s HTTP headers for rate limiting (ie
X-RateLimit-Reset), with one exception.
Do not use Github’s standard for the
X-RateLimit-Reset header. You can keep the same header name, but instead of showing a timestamp in the value of this header, show the number of seconds remaining before the rate limit resets.
Why ? Because the HTTP specification states that date formats should use the RFC 1123 (ie Fri, 09 Mar 2018 08:50:15 GMT). Hence, if you want to show a date in your
X-RateLimit-Reset header, you should use this format instead of a timestamp, but it's much more practical to use the number of remaining seconds.
This series of articles about Restful API design is also available as an eBook on Amazon, if you need it in a handy format.
Originally published at https://www.gvj-web.com on March 29, 2018.