Ever since my first car, I’ve always driven old BMWs from the 80s. I’ve probably had five of them over the past decade. They made great sense for a starving entrepreneur: they were cheap (i.e. <$2000) and they broke down only about once a year. Something was always wrong though. The driver’s side door lock wouldn’t work, or the heater wouldn’t work, or, most recently, the speedometer was busted. Until I bought that car, I had no idea how much we take our speedometers for granted.
It turns out that speedometers are pretty handy for API clients, too. Recently, I’ve heard from quite a few of our customers who’ve complained that it’s hard to utilize all of their available per-second rate limit. Most rate-limiting implementations (ours included) count the number of requests for a given time window (60 seconds for us) and then reject any requests that exceed the allowed number. This works well, but it’s difficult to code against, because you can’t easily tell if you’re under or over the limit, or if you’re likely to run over the limit before the time window resets.
Twitter’s and Github’s APIs have great implementations of this, and since
great artists steal it’s easier for our customers to code against something familiar, we used the same pattern. Here’s how it works:
$ curl -v "https://email@example.com&apiKey=XXXXXXXX" < HTTP/1.1 200 OK < Server: nginx/1.2.1 < Date: Tue, 26 Mar 2013 15:58:14 GMT < Content-Type: application/json;charset=UTF-8 < Content-Length: 5857 < Connection: keep-alive < Vary: Accept-Encoding < X-Rate-Limit-Limit: 600 < X-Rate-Limit-Remaining: 598 < X-Rate-Limit-Reset: 46
The cool part is these new HTTP headers in the response:
X-Rate-Limit-Limit: 600 X-Rate-Limit-Remaining: 598 X-Rate-Limit-Reset: 46
The English translation is that my API key has a rate limit of 600 requests per 60 second window (aka 10/s), I have 598 requests remaining, and the window will reset in 46 seconds.
For a bit more detail read our API docs. Happy speeding and let me know what you think!