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) {}
      });
    

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: 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"
}