Simple Rate Limits Try it

Setting up a rate limit is easy. Once you've registered you'll get an account ID and apikey (and this documentation will helpfully insert them into the code below).

Two things need to happen to use a rate limit. First, you need to define the LimitDefinition. You can do this in the Ratelim.it UI, but it's probably easier to do it in code that runs once during your code's initialization.

The first parameter to create a limit is the definition "group". This is the lookup key for the limit. The second parameters are the limit itself and the policy name which is essentially the time period. Let's see what a basic hourly rate limit would look like:

limiter =  RateLimit::Limiter.new(apikey: "ACCT_ID|APIKEY")

# only need to do this on startup
# limit to 1 per hour
limiter.create_limit("hourlytask", 1, RateLimIt::HOURLY_ROLLING)

if limiter.pass?("hourlytask")
  do_hourly_thing()
end
ApiClient apiClient = new ApiClient.Builder()
        .build();

apiClient.limitCreate(RateLimitProtos.LimitDefinition.newBuilder()
        .setGroup("hourlytask")
        .setLimit(1)
        .setPolicyName(RateLimitProtos.LimitResponse.LimitPolicyNames.HOURLY_ROLLING)
        .build());

if(apiClient.isPass("hourlytask")){
        System.out.println("do hourly thing");
}

Use the same limit definition multiple times Try it

Very likely you actually want to have a separate rate limit per user, per page, or per user per page. Luckily this is easy. The LimitDefinition group is a colon delimited string but when you lookup a limitdefinition you need not specify the whole thing. We'll find the closest matching limit definition. So for a definition like events:hourly you can call Ratelim.it for a limit on events:hourly:thing1. That will get the definition of events:hourly, but you'll get a different token bucket for thing1 than you will if you do it again for events:hourly:thing2.

limiter = RateLimit::Limiter.new(apikey: "ACCT_ID|APIKEY")

# only need to do this on startup
# limit to 1 per hour
limiter.upsert_limit("pageload", 1, RateLimIt::HOURLY_ROLLING)


if limiter.pass?("pageload:/my_account/login/:user12312")
   # this will fire
   TrackingService.trackPage(user12312, "/my_account/login/")
end

if limiter.pass?("pageload:/my_account/login/:user456")
   # this will fire
   TrackingService.trackPage(user456, "/my_account/login/")
end

if limiter.pass?("pageload:/my_account/login/:user456")
   # this won't fire because we're over user456's limit this hour
   TrackingService.trackPage(user456, "/my_account/login/")
end

Override limits Try it

Because we find the closest match, you can do handy things to override specific use cases. Let's say you want to limit firing usage events to once per event type per user per hour. That's great, but say there is a specific event that you only want to "debounce" and you'd like to fire no matter how many times it happens in an hour. Let's see how to accomplish that:

limiter = RateLimit::Limiter.new(apikey: "ACCT_ID|APIKEY")

# only need to do this on startup
# limit most pageload events to 1 per hour
limiter.upsert_limit("pageload", 1, RateLimIt::HOURLY_ROLLING)
# but on order_placed pages be sure to track them all by limiting to 1/sec
limiter.upsert_limit("pageload:/order_placed", 1, RateLimIt::SECOND)


if limiter.pass?("pageload:/my_account/login/:user12312")
   # this will fire 1 / hour
   TrackingService.trackPage(user12312, "/my_account/login/")
end

if limiter.pass?("pageload:/order_placed:user456")
   # this will match the more specific limit definition and fire 1/sec
   TrackingService.trackPage(user456, "/order_placed")
end

What limit policy types are available?