shacobox v2.0.0

ShacoBox

ShacoBox is a Node.js/io.js module designed to simplify the communications to the Riot API. Its manage your queries and your accesses to the Riot API.

IMPORTANT

To every developers using ShacoBox, the version 2.0.0 broke the compatibility with the previous one (1.2.2). To transfert your app, just initialize your the module that way:

// Create our Riot API reference
var riotApi = new ShacoBox.api(
    'my-riot-api-key',                          // Your API Key, see: https://developer.riotgames.com/
    10,                                         // 10 API calls max by 10 seconds
    500,                                        // 500 API calls max by 10 minutes
    {
        queryMod: ShacoBox.queryMods.SMOOTH,    // The scheduling policy used
        cache {
            summoner: true                      // Will cache everything related to summoners queries
        },
        attempts: 10                            // Will retry maximum 10 times if the server has an issue with our current query
    }
);

// Previously it would have been: var riotApi = new ShacoBox.api('my-riot-api-key', 10, 500, ShacoBox.queryMods.SMOOTH, {summoner: true});
// The attempts parameter did not exist then.

Installation

You can directly install ShacoBox from npm using:

> npm install ShacoBox

API Documentation

ShacoBox's documentation generated by JSDoc.

Getting started

Creating our first Riot API reference

First, it is important to understand how ShacoBox works.

I tried to make it quite easy to use for you (and me), and so some mechanisms have been set to help you not to worry about the management of your queries.

Every instance of ShacoBox has a priority queue which manage first the oldest queries and last newest ones and also manages your API queries limits.

// Load the ShacoBox npm module
var ShacoBox = require('shacobox');

// Create our Riot API reference
var riotApi = new ShacoBox.api(
    'my-riot-api-key'               // Your API Key, see: https://developer.riotgames.com/
);

Running our first query

When creating a new Riot API reference, every loaded module will create functions to access them by the API. Those function are named by the module's name in lower case:

riotApi.summoner();       // Summoner's module reference
riotApi.matchlist();      // MatchList's module reference

Every module contains its Riot API queries. We will run our first one looking for me on EUW server:

riotApi.summoner().getSummonersByNames(
    'euw',      // Region on which we are runing the query
    ['Mywäy'],  // Array of the summoners names to look for
    // Callback function, called once the Riot API answered us
    function (data, error) {
        // Lets have fun here!
    }
);

Valid modules are : champion, currentgame, featuredgames, game, league, lolstaticdata, lolstatus, match, matchhistory, matchlist, stats, summoner, team.

For more informations on the Riot API modules and their methods, I highly recommand you to browse the documentation. You will find everything you want on every part of this API.

Using priorities

At some point of your work, you possibly want to manage some priorities. Don't worry, we already though about it. Every ShacoBox instance have methods able to call every Riot API referencies with a different priorities.

To do so, just add the priority level before the module's name. Lets modify our previous example setting it a higher priority:

riotApi.urgent.summoner().getSummonersByNames(
    'euw',      // Region on which we are runing the query
    ['Mywäy'],  // Array of the summoners names to look for
    // Callback function, called once the Riot API answered us
    function (data, error) {
        // Lets have fun here!
    }
);

All we did is adding the "urgent" key between "riotApi" and "summoner()".

The valid priority keys are: urgent, important, low and verylow.

Using custom rate limits

While initializing your API instance, you can ask for a certain limit (lower than the default one or greater). To do so, just add the maximum queries you want to use every 10 seconds and every 10 minutes.

// Create our Riot API reference
var riotApi = new ShacoBox.api(
    'my-riot-api-key',              // Your API Key, see: https://developer.riotgames.com/
    10,                             // 10 API calls max by 10 seconds
    500                             // 500 API calls max by 10 minutes
);

Scheduling

It is possible to change the way your queries are scheduled. Currently we are supporting 2 kind of way to manage it:

• Running your most important query every X seconds (Smooth mod).
• Running your most important query as soon as possible (Early mod).

By default, the scheduling mod used is the smooth one.

Be careful using the early mod: it is possible that you appear to not be able to run a query for some times if you reach your API calls limit. If you plan to have a lot of queries, I highly recommand you to use the smooth mod for an higher availability of your services.

// Create our Riot API reference
var riotApi = new ShacoBox.api(
    'my-riot-api-key',                          // Your API Key, see: https://developer.riotgames.com/
    10,                                         // 10 API calls max by 10 seconds
    500,                                        // 500 API calls max by 10 minutes
    {
        queryMod: ShacoBox.queryMods.SMOOTH     // The scheduling policy used
    }
);

Caching

It is possible to use an in-memory cache, or any kind of caching system (by writting a very simple wrapper). To do so, you must add a new parameter when initializing your API instance.

// Create our Riot API reference
var riotApi = new ShacoBox.api(
    'my-riot-api-key',                          // Your API Key, see: https://developer.riotgames.com/
    10,                                         // 10 API calls max by 10 seconds
    500,                                        // 500 API calls max by 10 minutes
    {
        queryMod: ShacoBox.queryMods.SMOOTH,    // The scheduling policy used
        cache {
            summoner: true                      // Will cache everything related to summoners queries
        }
    }
);

As you can see, the caching parameters is in fact options. Here is the list of supported options.

By default, nothing will be cached, it is your work to determine what you do want to cache and what you don't.

Secure queries

From my experience, the Riot API tend to have some server side issues from times to times. I implemented a way to automaticaly retry to get data from queries victim of such a behavior. You can use it initializing ShacoBox that way:

// Create our Riot API reference
var riotApi = new ShacoBox.api(
    'my-riot-api-key',                          // Your API Key, see: https://developer.riotgames.com/
    10,                                         // 10 API calls max by 10 seconds
    500,                                        // 500 API calls max by 10 minutes
    {
        attempts: 10                            // Will retry maximum 10 times if the server has an issue with our current query
    }
);

By default, attempts worth 1, that mean we won't retry when a query is failed and simply raise the corresponding error.

How to get help?

You can get help here:

• Bug report
• Mail: vincent.marnier@gmail.com
• Reddit: /u/Cocottier
• LoL Contact: (EUW) Mywäy

Contribute

If this module helped you, please star it on github. That improve its visibility and so its usage and its quality.

Feel free to contact me if you are interested to contribute to this project.

Licence

The MIT License (MIT)

Copyright (c) 2015 Vincent Marnier

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.