Do you Speak Mogade?

Overview

Communication between a client and the mogade server happens via a REST interface over HTTP. Although the mogade libraries abstract the API away and provide a familiar interface, developers may still find the details useful. The information listed here is more of a high level overview of the mogade protocol. You really don't have to understand any of this to use mogade!

Basics

When learning the mogade API, it's safe to think of everything in terms of two categories: commands which are read-only and commands which aren't. A non read-only command always requires a key and a sig (more on these shortly); whereas a read-only command never requires a sig, might require a key, and always accepts an optional callback parameter (for use with JSONP).

The root of the API is http://api2.mogade.com/api/gamma/.

All responses are in JSON.

The Key

When you create a game in the mogade.com website, you'll get a game key. Drivers will typically ask for the game key as part of your configuration (perhaps when constructing a mogade object) and handle it internally from there on.

The Sig

The other parameter you get when creating your game is a secret. It is very important that you keep your secret..well..secret. The secret is used by drivers to generate a sig parameter. The sig parameter is a SHA1 hex-representation of all the other parameters, sorted by key, joined by a pipe | with the secret appended at the end.

What? Let's look at an example. Given a secret of shhhh and the following parameters q=power%20level&a=9001, we would sort and join the key values by pipe: a|9001|q|power%20level| and append the secret: a|9001|q|power%20level|shhhh. We could then SHA1 hash it and get the final value for the sig parameter: a02365b9a7e21c163d50a36e16b4d776f206adcc. Depending on your language, the SHA1 implementation might return a byte-array (or something similar), you'll need to convert this to a hexadecimal representaiton.

This approach has a couple nice benefits. First, only someone that knows your secret can submit requests. Also, even if a request is intercepted, all they can do is issue the exact same request - because any change to a parameter would require a new signature. Finally, the secret is never sent over the wire. This is why any request that has a sig, also requires a key - so that we can look up the secret on our side and make sure the signature is valid (by regenerating it from all the parameters and comparing is to the supplied one).

Player

Mogade works without requiring players to register or even be aware of mogade.com. This is achieved by internally identifying them using two key pieces of information: a username and a userkey. The username is provided by a user. The userkey is some type of unique identifier - say a device id - which most drivers handle internally. Combined, these two parameters uniquely identify a player yet allow for multiple players to use the same device.

Usernames are limited to 30 characters

Scores

The score endpoint is used to either get scores or save a score.

Save Score

You can save a score by POSTing to the scores endpoint. This command requires many of the basic parameters: key, sig, userkey and username. It also takes a lid which is the id of the leaderboard to save the score to and a points which is how many points the player got.

The command also accepts a special optional parameter called data. This is an arbitrary string you can store along with a score which'll be retrieved whenever you get scores out. This can include additional information, such as a level reached or time taken. We don't do any processing on this value, it's up to developers to encode and decode whatever is held in data. The field is limited to 50 characters.

The response is made up of two parts. The first is the rank of that score for that leaderboard across all supported scopes (daily (1), weekly (2) and overall (3)). The second part is whether or not this is a new high score for the player across the same scopes.

Get Scores

There are three different ways to get a score. They all involve GETint to the scores endpoint. In each case, you'll have to supply the leaderboard id as lid and a scope (daily (1), weekly (2), overall (3) or yesterday (4)). Also, as this command is read-only, an optional callback parameter can be supplied (for use with JSONP).

To get a page of score results, simply supply two additional parameters, the page and number of records. The first parameter is the 1-based index of where to start. The second is how many total records to retrieve - with an upper limit of 50.

Instead of supplying a page parameter, you can opt to supply a username and userkey parameter. This will return a leaderboard located around the specified user. Please note that this is a best-guess effort and may return the wrong page should the player be tied with a high number of other players. This method also accept a record parameter

Finally, if you take the above parameters but supply a record of 1, then you'll only get that player's score for the specified scope. This will always work regardless of ties.

However you call it, get scores returns 0 or more scores. This includes the username, points, date and date of the score. Additionally, in the first two cases, the page is returned.

Achievements

The achievement endpoint is used to either get achievements or grant achievements.

Grant Achievement

You can grant an achievement by POSTing to the achievements endpoint. This command requires many of the basic parameters: key, sig, userkey and username. It also takes a aid which is the id of the achievement to grant.

If this is the first time the player has earned the achievement, the achievement id and how many points it is worth will be returned. Otherwise, an empty response is returned.

Get Achievements

To get all of the achievements a player has earned in your game, you can GET the achievements endpoint. This command takes the key, username and userkey. Also, as this command is read-only, an optional callback parameter can be supplied (for use with JSONP).

As a response, you'll get an array of achievement ids which the player has earned.

Log Error

You can POST to the errors endpoint to log any error and have access to the details through mogade.com. This command requires a key and sig. It also requires a subject which is a short (up to 150 character) description of the error. You can optionally supply a details parameter which can be up to 2000 characters.

This command does not return a value.

Log Start

You should POST to the stats endpoint whenever your game starts up. This allows for the collection of basic usage statistics. This command requires a key, sig and userkey.

This command does not return a value.

Ranks

You can get a player's current rank by GETting the ranks endpoint. This takes the leaderboard id as lid, the username and userkey. You can optionally specify one or more scopes (daily (1), weekly (2), overall (3) and yesterday (4)). By default, all scopes are returned.

The response is the rank of the player score for that leaderboard across the specified (or all) scopes.