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-Limit, X-RateLimit-Remaining and 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.

If you want to read all of the articles of the series “ Pragmatic decisions for your RESTful API”, you can start here. The next article will focus on authentication of your RESTful API.

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.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store