Ztd.Blunders Api Reference

Introduction

In next sessions we will cover Blunder service's public API. This API is based on token authorization and extremely easy to use.

To make things less complicated, we wrote wrapper library to make cross-domain queries easy and intuitive to use. Just add this to your project and use as following


      sync.ajax({
          url: 'https://chessblunders.org/api/mobile/...',
          crossDomain : true,
          data: {
              token: 'your-token'
          },
          onSuccess: function(result) {},
          onFail: function(result) {}
      });

You will need to specify your request in url field, for example /blunder/get at the end of the path.
Data field is the javascript object directly translated to json and passed to server as request description.
Field token is necessary data to pass to server with each request, we will assume this by default and not write in following examples.

In next topics, we will only provide json data, translated from data object, explaining previous example it will be look like


      {
        'token': 'your-token'
      }

Note: we also have old API, based on session authorization, but it is deprecated and not supported anymore. Our web site still use this API for historical reasons.

You can work with blunders in several different modes.

Blunders

/api/blunder/get

Get random blunder from server database. If user is not logged in, new random blunder is always returned.
If user is logged in, return already assigned blunder for user of given type. If none assigned, assign and return new blunder.
Two modes are possible according to "type" argument:

type:rated
When user will solve the blunder, it will affect it's rating and be recorded into statistics and history.
type:explore
Optional argument id to get blunder with specific identification number. Blunder will not effect user's rating and statistics.

Request example:

{
    "type": "rated"
}

Response example:

{
    "data": {
            "blunderMove": "Bxb6",
            "elo": 2296,
            "fenBefore": "2k1r3/pp4pp/1n5b/B1p2P2/2P1p3/PP1r1BP1/4K2P/1R5R w - - 2 22",
            "forcedLine": ["Re3+", "Kf2", "Rxf3+", "Kg2", "axb6"],
            "id": "557ae090e13823b818db76b6",
            "move_index": 42, "pgn_id": "554dcb33e1382385749b7e9e",
            "pv": ["Re3+", "Kf2", "Rxf3+", "Kg2", "axb6", "Rhf1", "Rc3", "a4", "Bg5", "Rf2", "Kc7", "Re2", "Re5", "g4", "Re8", "Kg1", "Rd3", "Kg2", "Kc6", "Rbb2", "e3", "Kf3", "Rd1", "Ra2", "Rf1+", "Kg2", "Rb1", "Kg3", "Re4", "h4", "Bf6"]
            },
    "status": "ok"
}

/api/blunder/info

Get information on given blunder. Use blunder_id argument to specify blunder.
Request example:

{
    "blunder_id":"557ae090e13823b818db76b6"}
}

Response example:

{
    "data":
        {
        "comments": [],
        "dislikes": 0,
        "elo": 2296,
        "favorites": 0,
        "game-info":{
            "Black": "Unknown",
            "BlackElo": "?",
            "White": "Unknown",
            "WhiteElo": "?"
            },
        "likes": 0,
        "myFavorite": false,
        "successTries": 0,
        "totalTries": 0
        },
    "status": "ok"
}

/api/blunder/validate

Send user's solution to server. User's rating and statistics can be changed as a result of user's moves.
Request example:

{
    "id":"557ae090e13823b818db76b6",
    "line":["Bxb6","Rd4"],
    "spentTime":1293,
    "type":"rated"
}

If user is logged in and user's rating affected, we return user's rating change and new Elo.
Response example:

{
    "data": {
        "delta": -15,
        "elo": 1270
        },
    "status": "ok"}
}

/api/blunder/vote

Vote for a blunder. Valid only for authorized user. vote argument can be +1 for positive vote and -1 for negative.
Request example:

{
    "blunder_id":"5580f5afe13823b83b0095e1",
    "vote":1
}

Response is the blunder information as it is returned by /api/blunder/info .
Response example:

{
    "data": {
        "comments": [],
        "dislikes": 0,
        "elo": 1420,
        "favorites": 0,
        "game-info": {
            "Black": "Unknown",
            "BlackElo": "?",
            "White": "Unknown",
            "WhiteElo": "?"
            },
        "likes": 1,
        "myFavorite": false,
        "successTries": 0,
        "totalTries": 1
        },
    "status": "ok"
}

/api/blunder/favorite

Set blander user's favorite. Valid only for authorized user. If blunder already a favorite, removes it from favorite list.
Request example:

{
    "blunder_id":"5580f5afe13823b83b0095e1"
}

Response is the blunder information as it is returned by /api/blunder/info .
Response example:

{
    "data": {
        "comments": [],
        "dislikes": 0,
        "elo": 1420,
        "favorites": 0,
        "game-info": {
            "Black": "Unknown",
            "BlackElo": "?",
            "White": "Unknown",
            "WhiteElo": "?"
            },
        "likes": 1,
        "myFavorite": false,
        "successTries": 0,
        "totalTries": 1
        },
    "status": "ok"
}