rest

The Basics

Create an API Handler:

String token = "your-api-key";
ApiHandler handler = new ApiHandler(Shard.EUW, token);

For each REST target, there is at least one method in the handler, though a lot of times, there will also be convenience methods, such as getSummonerId(String name) to map directly from names to summoner ids. Each method, unless specified otherwise, will count as one request towards your rate limit (note that requests to static-data do not count).

long summoner = handler.getSummonerId("Froggen");
RankedStats season3Stats = handler.getRankedStats(summoner, Season.SEASON3);

Throttling your requests

Obviously, for larger applications, you will run into problems with the API's rate limit. For this purpose, ThrottledApiHandler automatically manages the rate limits for you, executing requests in the background as fast as the rate limit allows.

Creating a rate limit is a simple as creating a Limit object:

Limit limit = new Limit(500, 10, TimeUnit.MINUTES); // Read as "500 requests in 10 minutes"

Pass those limits to the constructor of ThrottledApiHandler:

ThrottledApiHandler handler = new ThrottledApiHandler(shard, token, 
                                                      myLimit1,
                                                      myLimit2,
                                                      myLimit3);

Note how there is no limit as to how many limits you can specify.

ThrottledApiHandler supports exactly the same methods as the regular ApiHandler, however every method will return a Future instead, where T would be the type that ApiHandler would have returned. As soon as the method is called, the request is scheduled. If all rate limits permit execution of the request, it will be executed immediately, otherwise, it will be executed once all limits permit and no other request is in the queue before this one. The get()-method of the Future will block until the request is returned.

Future<Long> summoner = handler.getSummonerId("Froggen");
RankedStats stats = handler.getRankedStats(summoner.get()).get(1, TimeUnit.SECONDS); // Wait at most one second

Since ThrottledApiHandler uses an internal Timer, you should invoke handler.close() when you are done using it (it implements Autocloseable, so try-with-resources works too). After this point, while some requests are still executed, no guarantees are made whether Future.get() will return or not.