MINIPLAY S2S REST API APIs for casual & social games

Preface:

Please help us improving it by reporting us any bugs or suggestions to [email protected], we put our best efforts in order to make life easier for you and the other developers, and your help will be greatly appreciated.

In this document we’ll dig into the REST API for server to server communications. Please refer to the MINIPLAY APIs OVERVIEW document first if you haven’t read it yet, knowledge of the concepts explained there is required.

As a convention, we will use red for required parameters and blue for optional parameters. Also be noticed that every timestamp is handled with a precision of milliseconds (POSIX timestamps only have a precision of seconds).

Any api_key or user_token used here are not valid, please use the data we’ve provided you.

1. Introduction

By accepting stateless GET/POST HTTP* requests, this REST API provides full, secure read/write access to our API servers. Use your private api_key to identify your game. Please note this API is intended only for server to server communications, do not make calls that could be intercepted by third parties, specially if they’re originated on clients

* It’s within our plans to support the HTTPS protocol soon. When no method is specified, a HTTP GET is assumed.

1.1 Sandbox template

Our Server 2 Server API is mainly used by games that are self-hosted and running inside an iframe in our sites, in that case you must handle all the GET parameters that we send you, to help you with that task,
you can begin by downloading our Sandbox template with the JS API(link to the JS API doc)

The sandbox template will take care of all the initialization & parameters validation (user token, user locale...) and will also initialize our Javascript API that allows your game to interact with your site.

If your game is external and won't run inside our sites you must remove the parameters validation part, no parameters or signature will be provided, only the user_id & user_token when the user connects with Miniplay Connect.

The status object include all the info related with the processing status of the request, as you can see, a the status.success property indicates whether or not the request was successful, you can easily evaluate it for true or false. The other properties indicates the response type, response HTTP code and status message if there was any.

The data object include the information returned from our servers, from now on, when we talk about the data returned by the API, we will always be referring to the properties included in the data object.

4. Handling error responses

In case there’s something wrong with your request, you’ll receive the corresponding HTTP STATUS code in the HTTP headers, but a JSON document will still be returned (even for 404 errors), including a third object, exception, with the error details, here’s an example:

Most of error responses will come from malformed requests, but very bad things can happen, so, be prepared to receive anyone of the following strings at status.type:

BAD_REQUEST

UNAUTHORIZED

FORBIDDEN

NOT_FOUND

SERVICE_UNAVAILABLE

INTERNAL_SERVER_ERROR

On the contrary, exception.type can be one of the multiple exceptions that our system raises, we recommend you to ignore it, just use the exception.message to get a more detailed explanation of what happened.

5. USER module

Allows you to authenticate users, get their details, followers, subscriptions and friends.

Please remember that the user id is the unique and immutable identifier of our users, on the other side, the alphanumeric user uid is unique as well, but mutable, it can be changed by the user and fetched by a different one. Never treat the user uid as immutable data.

5.1 Get detail

Retrieves the user detail including social totals (followers, subscriptions, friends...)

Urlhttps://api.minijuegos.com/lechuck/server/user/[user_id]

Parameters

api_key

user_tokento get the full user detail

Responsedata.userObject with the public detail, or full detail if user_token was provided.

Here are some of the most interesting user data returned:

stringdata.user.iduser id. immutable

stringdata.user.uiduser uid / nick / alias. mutable

numberdata.user.profileurl of the user profile mutable

numberdata.user.progress_levellevel of the user mutable

stringdata.user.avatarurl of public avatar immutable(96x96 jpg)

stringdata.user.avatar_miniurl of public avatar immutable(32x32 jpg)

stringdata.user.avatar_bigurl of public avatar immutable(256x256 jpg)

stringdata.user.avatar_alphaurl of public avatar immutable(96x96 png)

If you provide the user_token and its valid, the following properties will be available:

5.3 Subscriptions

This is probably the most important list for game developers, this method gets the subscriptions list of an user (the subscriptions are the users that he/she follows), ordered by descending timestamp, can be easily paginated by using the timestamps.

withInstalledto include installed flag (played the game?, false by def)

limitnumber of items to retrieve (20 by default)

fomTimestampoldest timestamp (in milliseconds), inclusive

toTimestampnewest timestamp (in milliseconds), exclusive

Response

status.subscriptionstrue if the user_token is valid.

data.userArray of users (with public detail if requested)

Every user in the list will contain the time property corresponding to the millisecond timestamp (64bit) when the event occurred (in this case, the subscription of the provided user). It will contain as well the is_friend boolean flag and the is_installed boolean flag (if requested).

5.4 Friends

Gets the friends list of an user (those who are both being followed by and following the provided user), ordered by descending timestamp, can be easily paginated by using the timestamps. Remember: users can only communicate and share things with their friends.

Urlhttps://api.minijuegos.com/lechuck/server/user/[user_id]/friends/

Parameters

api_key

user_token

withDetailto include users public detail (true by default)

withProgressto include users progress (level, false by default)

withInstalledto include installed flag (played the game?, false by def)

limitnumber of items to retrieve (20 by default)

fomTimestampoldest timestamp (in milliseconds), inclusive

toTimestampnewest timestamp (in milliseconds), exclusive

Response

data.friendsArray of users (with public detail if requested, Refer to 5.3).

Every user in the list will contain the time property corresponding to the millisecond timestamp (64bit) when the event occurred (in this case, the friendship). It will contain as well the is_installed boolean flag (if requested).

6. STAT module

Allows you to send, retrieve and reset game stats for users to track their progress. All configured stats for your game are listed in your development sandbox, give them a look and don’t hesitate to ask us for as many as you want, we love stats!. Please read first theMINIPLAY SOCIAL COMPETITION document for better information and examples.

Please remember that in order to operate with stats, they must be previously configured by us, the stats configured & available for your game are listed in your game development page (IN-GAME STATS tab).

6.1 Retrieve a stat

Gets the game stat for the user.Replace the [stat_uid] with the stat uid that you want to read (must have been created by us or it will return a not found).

6.2 Send a stat

Sends a game stat for the user, it will be automatically handled according with the stat type (REPLACE, MIN, MAX or SUM), so it may or not be saved. Please do not spam our API servers with user stats constantly, there’s no problem receiving a few stats each minute, but they perform a lot of complex operations (highscore checking, achievements...), we will be destroyed if we receive stats each time an user shoots a bullet, instead of that, accumulate them and send the total once the user finishes the level. We do track how many stats each API clients sends ;)Replace the [stat_uid] with the stat uid that you want to send (must have been created by us or it will return a not found).

Urlhttps://api.minijuegos.com/lechuck/server/stat/[stat_uid]/put/

Parameters

api_key

user_id

user_token

value32 bit integer value, if you need floating point, multiply it for. The highest number supported is

6.2 Send a batch of stats

Allows you to send a batch of multiple stats in just one RPC connection. You can provide as much stat_[stat_uid] parameters as you need with their corresponding values. The response will contain all the results and the errors if there are any.

Urlhttps://api.minijuegos.com/lechuck/server/stat/batch/

Parameters

api_key

user_id

user_token

stat_[stat_uid]32 bit integer value for the stat. You can provide as much as you want

Response

data.errors object with the stats errors (if any).

data.results object with the results of the stats sent.

Here are some of the most interesting data returned:

data.results[x].statSavedthe result of the operation

data.results[x].statValuethe value saved (if its SUM, the total)

data.results[x].highscoresSavedthe list of related highscores updated if any

In this example, we send the value of a 3 demo stats: 'points', 'time' & 'monsters' (that must exist).

7. HIGHSCORE module

Allows you to retrieve scoreboards and positions for users. Remember that all high scores are tied with the stats sent, there are no methods to put scores directly into the scoreboards. You can ask us for as many scoreboards as you like to have, just tell us their sorting method (ASC or DESC), their computation method (SUM, MAX, MIN) and the stat uid that will be sent. The stat type is ignored, we always use the last value sent to calculate its position into the scoreboard. Please be noticed that SUM scoreboards doesn’t have timespans other than TOTAL.

Please remember that if you multiply the stats to handle floating point numbers in your game the highscore will also be stored multiplied, you have to divide them by 10^x in order to get the same precision for displaying it. In our sites we do that automatically, so you don’t have to worry about it, just tell us how many decimal numbers the stat & the highscore have.

In order to operate with highscores, they must be previously configured by us, the highscores configured & available for your game are listed in your game development page (click on the achievements & highscores icon if they're not present by default).

7.1 Get global scoreboards

Gets a global scoreboard, they will be ordered as configured, starting from the best, the items can be easily paginated by using the score and the timestamp of the last item of the batch.

7.2 Get user social scoreboard

Gets a “friends” scoreboard for an user, the friends scoreboard corresponds to a board where only shows the user and the users he/she is following. As soon as the user follows a new one, its score will be sent to the user friends scoreboard, the same happens when the user stops following an user, it will be removed from it. The scores will be ordered as configured, starting from the best, the items can be easily paginated by using the score and the user id of the last item of the batch.

7.3 Get score

Retrieves an user score from a scoreboard (this value may be different from the one reported by getting the stat value, because the scoreboard can have different sorting or computation methods than the stat.

8. SHARED CONTENT module

This module allows you to save and retrieve user created shared content (like levels for your games, replays, etc). One of the most interesting features we provide is that they can be associated with highscores: when you post a stat (6.2) and it’s good enough to produce an update in a scoreboard, a highscoresSharedContentId is returned as well, in case you want to store related data (by issuing a shared content put request afterwards). Here’s one good use-case: You’ve got a racing game, and after each race you have the full lap serialized into a string or bytearray, you can store it, display the best times scoreboard and let your users compete against the best. When loading scoreboards, you can retrieve the associated sharedContentId as well.

There’s no limit in the amount of total data you can store, but each shared content slot can only store 50kb of data. Do not spam our servers with data, we track each game storage usage.

8.1 Get data

Retrieves the shared content data.

Urlhttps://api.minijuegos.com/lechuck/server/sharedcontent/[id]/

Parameters

api_key

Response

The stored data as a binary application/octet-stream (or 404 if empty)

10.5 Increment an user item stock

Increments the stock of an user item, or give the item to the user if doesn’t have it already. This is only allowed if the item is non purchasable, items that can be purchased with Minicoins cannot be incremented in any ways. If you need to increment a purchasable item we could suggest to have a separated item (non-buyable) that can be tracked or aggregated with the purchasable one value. If the item stock exceeds

10.7 Item purchases & server callbacks

The purchase workflow must be initiated by our client APIs: Javascript or Actionscript 3. Once the user has purchased some items, we’ll send you a signed HTTP POST request to your callback notify you the operation:

Timeout:3 secondsThe request is synchronous, make sure you can answer within this time frame.

Do not forget to check that the “event” property is “buy-item”, this same schema could be used to notify other type of events (i.e. when an user likes/shares your game) to allow you tracking them. PHP Example:

$jsonString = file_get_contents("php://input"); /* Get the RAW POST DATA */
if ( ! ( isset($_SERVER['HTTP_MINI_SIGNATURE'])
&& $_SERVER['HTTP_MINI_SIGNATURE'] == md5("[YOUR_API_KEY]".$jsonString) )) {
throw new Exception("Invalid signature");
}
/* Decode the JSON string received and convert it to an associative array */
$json = json_decode($jsonString, true);
if (isset($json['event']) && $json['event'] === "buy-item")) {
/* It's an item purchase event!, 'event_payload' contains the purchased items. What to do now?: */
/* a) If you have your own economy or inventory management, you can
ignore the payload and just read the user inventory and consume
every items you found to remove them from our system.
Please DO NOT EVER add them to your inventory without consuming
them from our inventory. */
/* b) If you don't have your own economy you can probably
just log this message */
}

If you have your own economy or inventory management, you MUST CONSUME the items from the user inventory in our system. Do not ever add
them to your inventory without consuming them from ours, if you don't do that, the user will still have the item and we couldn't know if it has been added to yours.

Some games have isolated payment gateways that only receives notifications and cannot be modified to make calls to our API (for consuming/removing
the items from the user inventory after registering the transaction), in that case, you can return a plain 'AUTOUSE' (without quotes).
If that string is returned in conjunction with an HTTP 200 status code, our system
will automatically consume the items from the user inventory without requiring you to do that.Please make sure your response is a plain UTF-8 string, nothing else.

This operation mode is discouraged. You should stick to make calls to the REST API to consume the items, that way, you can be 100% sure the items
are correctly decremented from the user inventory in our system.

10.8 Promotions, discounts & item pre-validations

In order to provide you more security and/or the ability to decide whether or not an item can be sold to an user (i.e. promotions, discounted or special items), we support S2S item pre-validations (for all or for a few items), in this case, we'll request your authorization (via an S2S callback) for every item purchase. This pre-validation will happen twice, first, prior the user purchase, and lastly, prior the user confirms the purchase. I.e, for items which can be sold only once, you should invalidate the future purchases of the item only when you receive the buy-item event, meaning that the user has purchased the item.

We don't support discounts, but this can be easily overcomed by creating new items which can be sold for less money, letting you to decide when an user can buy them or not. There's no limit in the amount of items you can ask us to configure.

By default, all items don't require pre-validation and can be sold, you must ask us to enable it for some items. Please provide us a list of items that have to be validated and both production & development urls for your validation callbacks. If no custom urls are provided, we'll send the notifications to your standard callback urls, for simplicity, we recommend you to use the same urls for all callbacks.

10.9 Dynamic items

For selected developers and complex games we support an additional type of items called "dynamic", which allows you to set a custom title and price for an item when you initiate the purchase workflow via any of our client apis. To prevent any modification of the payload, these items purchases must be validated server-side, we will always ask you if the user can purchase the dynamic item with the data that you provided us.

You can initiate the workflow of dynamic items just like standard ones, but, instead of providing the amount to purchase for the item, you have to provide an string with the dynamic item payload like this:

Only one dynamic item can be sold at the same time, only 1 unit of the item can be sold.

The price in minicoins is not your net share, it's the amount that the user has to pay for it, the amount you specify is the amount that will be charged to the user. It must be an integer.

You have to provide the name in the user locale language, your game receive the user locale as parameter.

The icon is optional and provisioned for the future, it's not yet supported, we recommend you to leave it empty or provide a 128x128px transparent png url.

After the third | you can specify whatever you need, like an internal item id, you can even include more | symbols.

The payload max length is 700 characters, including icon

VALIDATION OF DYNAMIC ITEMS

You're responsible for the validation of the dynamic item, we'll send you a callback with the purchase request including the payload data you specified. By returning 'OK' you acknowledge that the price & name of the item is correct, and that the user can purchase it. You can (and you should) add as much data as you need to the payload in order to verify it and to prevent users from purchasing items they're not allowed to (like a transaction id or a signature...)

Dynamic items will be notified just like regular items, but you'll receive the "dynamic_payload" property you provided us inside them so you can process it for your game (Check RAW POST DATA at 10.7 Item purchases & server callbacks).

Important: Given the nature of dynamic items, they doesn't need to be consumed, they will be automatically consumed after they're notified to your S2S callback. We don't store an inventory of dynamic items. If you're manually consuming items from the user inventory you must ignore "dynamic" items.