BinaryBeast API

From BinaryBeast

Jump to: navigation, search

Contents

Overview

The BinaryBeast API is available to all registered BinaryBeast users. Authentication is handled by supplying your APIKey or with a simple email / password combination


If you find that anything in this page is innacurate or missing, please let us know at contact@binarybeast.com


The default return format is JSON, but you may request XML or even CSV by passing the argument APIReturn=[json,xml,csv]


Where to send the requests

All requests are routed through a single URL: https://api.binarybeast.com/

Get an API Key

We recommend using an APIKey instead of a standard email / password combination (though you can still do that if you wish)


You can get your APIKey by logging into BinaryBeast.com - and visiting Settings top right, or visit the following page: http://binarybeast.com/user/settings/api


Debugging

Registered users now have the option of viewing their recent API Requests in their User Settings

There's a new tab called "API Activity/History" - click on it and you'll get a list of recent requests

You can even drill down into each request and view every detail about it - all arguments you sent, and exactly how the server responded


Naming conventions

BinaryBeast was developed using CamelCase arguments / variables. Naturally therefore, the API also uses that same format


However, you can (and the PHP class does this by default in fact) pass an argument api_use_underscores with a value of 1, and it will convert all incoming / outgoing arguments through the API to allow for using underscore_seperated_values


If api_use_underscores is enabled, for example 'APIKey' would become 'api_key', and TourneyTeamID becomes 'tourney_team_id' - just seperate each word with an underscore


Remember that this works BOTH ways - all arguments sent to the API can use underscores, and all returned value keys will be in the snake_case format


Important note: all arguments accepted are NOT case sensitive - TourneyID works just as well as tourneyid


Standardized responses

All services return an array, and 'Result' is ALWAYS included. The value of 'Result' roughly resemble HTTP result headers. IE 200 = the service executed successfully, 500 = internal error, 403 = un-authorized.


Please note: If using our pre-made PHP class, all returned values are objects


Service requests

When calling upon the API, there is 1 mandatory argument called APIService - which tells BinaryBeast exactly what you want to do


The API requests call upon a repository of services, and are broken down by Package.Group.Service


A common example of a service request is from the Tourney package, the TourneyCreate group, and the Create service, like this: Tourney.TourneyCreate.Create - As you hopefully guessed, this would be used to create a new tournament


Authentication

There are 2 methods of authentication, and along with them, a few mandatory arguments for all api calls:


When using an API Key, you MUST include the following 2 mandatory arguments:

APIKey: Your API key - See the heading Get an API Key for directions on how to get this value

APIService: The service to call, ie Tourney.TourneyCreate.Create


You may also use a standard Email / Password combination, in which case the following there are 3 mandatory arguments:

APIEmail: Your BinaryBeast login email

APIPassword: Your BinaryBeast password

APIService: The service to call, ie Tourney.TourneyCreate.Create

Pre-made interfaces

PHP

We have already made a PHP class that does all of the work for you - you can download it On GitHub

Current revision: 3.0.6 (2013-04-19)


You can view the documentation on BinaryBeast.com


Example usage:

//Get the main API Class
//Make sure you setup the values in lib/BBConfiguration.php!
require('BinaryBeast.php');

//Instantiate the main class
$bb = new BinaryBeast();

//Let's create a tournament!
$tournament = $bb->tournament();
$tournament->title = 'Test Touranment!';

//Uh oh! time to troubleshoot
if(!$tournament->save()) {
    var_dump($bb->error_history);
}

//Success! let's print out a link to the tour
else echo '<a href="' . $tournament->url . '">Check out my new tournament!</a>';

Java

We recently released a set of simple java classes that can be used to access the API, - you can download it here

Current revision: 1.0 - 2011-8-1 (clear your cache if you need to download a fresh copy)

However, we haven't had a chance to document it's usage yet, so ask us directly or figure it out on your own :), we're working on it though


You can view the limited class documentation here


Example usage:

import org.json.JSONArray;
import org.json.JSONObject;
import com.binarybeast.api.BBRequest;
import com.binarybeast.api.BBRequestHandler;
import com.binarybeast.api.BBResult;
import com.binarybeast.api.BinaryBeastAPI;

public class main
{

        /**
         * @param args
         */

        public static void main(String[] args)
        {
                /*
                 * Though we don't actually need to save an instance, we still need to instantiate the class so it can be
                 * accessed from BBRequest later, and so it can remember our APIKey
                 */

                new BinaryBeastAPI("e17d31bfcbedd1c39bcb018c5f0d0fbf.4dcb36f5cc0d74.24632846");

                //Simple debugging / testing, as this is a simple cli application
                System.out.println("Thanks for testing, welcome to the BinaryBeast API Version: " + BinaryBeastAPI.API_VERSION);

                /**
                 * Simple call - search through our list of games for any that have the word "star" in it
                 */

                BBRequest.gameSearch("star").execute(new BBRequestHandler()
                {
                        @Override
                        public void onResponse(BBResult result)
                        {
                                /**
                                 * Success!!!!
                                 *
                                 * For EVERY SINGLE REQUEST RESPONSE, result will be returned, and will roughly reseumble an http result code
                                 *
                                 * 200 ALWAYS means that the request was successful
                                 *
                                 * A few common possibilities:
                                 *              401: You're not logged in
                                 *              403: You don't have permission
                                 *              500: Internal error (hopefully you NEVER see this, contact us immediately if you do)
                                 */

                                if(result.result == 200)
                                {
                                        //Let's loop through the results
                                        JSONArray games = result.optJSONArray("Games");
                                        for(int x = 0; x < games.length(); x++)
                                        {
                                                JSONObject game = games.optJSONObject(x);
                                                System.out.println(x + ": " + game.optString("Game") + " (GameCode: " + game.optString("GameCode") + ")");
                                        }
                                }
                                else System.err.println("Response Error: " + result.result);
                        }
                });
        }

}


If you would like to help out the API, send us your own API class in another language to contact@binarybeast.com. We'd love to add it here after looking it over


Credit

Should anyone be so kind as to send us their own class / interface to the BinaryBeast API, full credit goes out to him of course, just let us know how credit should be given


Packages

Tourney Package

CRUD services for managing tournaments


Game Package

This package can be used to lookup games from our database, and retrieve their GameCodes


Country Package

This package can be used to lookup countries from our database, and retrieve their CountryCodes


APICallback Package

This package is used to create custom event callbacks,

For example, when a tournament is completed, it will notify you by calling the URL you supply and it will pass along a bit of information about the event, as you would expect from a CallBack

Personal tools