REST API Calls

1. User clicks the Bramble Authorize Button

---

Opens up the Bramble Authorization Page. The user puts in his username and password and then is redirected back to the game.

• URL

  /bramble?response_type=code&client_id=client_id&redirect_uri=callback_url&state=teststate&scope=profile

• Method:

  GET

• URL Query Params

  Required:

  response_type='code' (example: 'code')

  client_id=[String] (example: 'mansim')

  redirect_uri=[String] (example: 'http://armygrid.com/callback/')

  state=[String] (example: 'teststate')

  scope=[String] (example: 'profile')

• Success Response:

  • Code: 200
    Content: Opens the Bramble Authorization Page for the user

• Error Response:

  • Code: 400
    Content:
    { "statusCode": 400, "status": 400, "code": 400, "message": "Invalid client: redirect_uri does not match client value", "name": "invalid_client" }

  • Code: 400
    Content:
    { "statusCode": 400, "status": 400, "code": 400, "message": "Invalid client: missing client grants", "name": "invalid_client" }

  • Code: 400
    Content:
    { "statusCode": 400, "status": 400, "code": 400, "message": "Unsupported response type: response_type is not supported", "name": "unsupported_response_type" }

• Sample Call:

  window.open('https://brambleapi.herokuapp.com/bramble?response_type=code&client_id=mansim&redirect_uri=http://armygrid.com/callback/&state=teststate&scope=profile', '_self');
  

• Notes:

  The user will be redirected after the authorization step to the callback url of the game. The authorization code will be attached to the callback url ( Example: http://armygrid.com/callback/authorization_code ). Extract the authorization_code value and use it in the next request.

2. Authorization Grant Request

---

The access Token which will help you to send reward data to Bramble API is received in this request.

• URL

  /grant

• Method:

  POST

• Header Params

  Required:

  Authorization='Basic ' + btoa('client_id:client_secret_id)'

• Body Params(raw JSON):

  { "grant_type":"authorization_code", "code":"authorization_code_recieved_in_the_previous request", "redirect_uri":"armygrid.com/bramble_callback/" }

• Success Response:

  • Code: 200
    Content: { "accessToken": "199146e7e010ffa216301333b4c8cc14b9184958", "accessTokenExpiresAt": "2020-03-24T13:34:07.337Z", "scope": "profile", "refreshToken": "1dcabd1c75520b4b8567517fc8cd0a8e218865b2", "refreshTokenExpiresAt": "2020-04-24T21:21:56.017Z" }

• Error Response:

  • Code: 400
    Content: { "statusCode": 400, "status": 400, "code": 400, "message": "Invalid grant: authorization code has expired", "name": "invalid_grant" }

• Sample Call:

    //JS
        var xhr = new XMLHttpRequest();
        authURL = "https://brambleapi.herokuapp.com/grant";
        xhr.open('POST',authURL, true);
        xhr.setRequestHeader("Authorization","Basic "+ btoa("mansim:armygrid"));
        xhr.setRequestHeader("Content-Type", "application/json"); 
        var data = JSON.stringify({ "grant_type": "authorization_code", "code": "335c162ae937c0ece349fdea6d57ec0e8160100d", "redirect_uri":"armygrid.com/bramble_callback/" });
  
        xhr.onreadystatechange = function() {
  
        if (xhr.readyState == XMLHttpRequest.DONE) {
                alert(xhr.responseText);
            }
        }
        xhr.send(data);
  

  // Request module Nodejs 
  var postData = {
    "grant_type": 'authorization_code',
    "code":"335c162ae937c0ece349fdea6d57ec0e8160100d",
    "redirect_uri": 'http://armygrid.com/bramble_callback/'
  }
  
  var options = {
    url: 'https://brambleapi.herokuapp.com/grant',
    method: 'POST',
    headers: {
    "Authorization":"Basic " + btoa("mansim:armygrid")
    },
    body:postData,
    json:true
  };
  
  function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body.accessToken);
      console.log(body.refreshToken)
    }
    else{
      console.log(body);
    }
  }
  
  request(options, callback);
  

• Notes:

  You will get two tokens. Refresh Token and Access Token. Refresh Token is the one which doesn't expire frequently but Access token expire frequently. This Access Token will help you in sending the Achievement Data to the Bramble API as seen in the next request.

3. Simple Achievement Data GET Request

---

Request which will send Achievements data of the user to Bramble API. So if a user has completed a particular achievment the game can send data to Bramble API with this request.

• URL

  /achievement/armygrid/:achievement_name

• Method:

  GET

• URL Params

  Required:

  achievement_name=[String] (example: 'sample_achievement_2')

• Header Params

  `Authorization='Bearer ' + access_token_received_in_grant_request`
  

• Success Response:

  • Code: 200
    Content: Added Achievement Successfully

• Error Response:

  • Code: 401
    Content:
    { "statusCode": 401, "status": 401, "code": 401, "message": "Invalid token: access token has expired", "name": "invalid_token" }

  • Code: 401
    Content:
    { "statusCode": 401, "status": 401, "code": 401, "message": "Invalid token: access token is invalid", "name": "invalid_token" }

  • Code: 500
    Content:
    Achievement Already Added

  • Code: 501
    Content:
    No such achievement

• Sample Call:

        var xhr = new XMLHttpRequest();
        var achievementURL = "http://brambleapi.herokuapp.com/achievement/armygrid/sample_achievement_2";
        xhr.open('GET',achievementURL, true);
        xhr.setRequestHeader("Authorization","Bearer "+ "199146e7e010ffa216301333b4c8cc14b9184958");
        xhr.onreadystatechange = function() {
  
        if (xhr.readyState == XMLHttpRequest.DONE) {
                alert(xhr.responseText);
            }
        }
  
        xhr.send();
  

• Notes:

  After the achievements are sent to the Bramble API. The Bramble API rewards the user Brambles and the reward is reflected in the Bramble Wallet of the User.

4. Renewing Access Token / Refresh Token to get back access to the Bramble API

---

Sometimes the Access Token / Refresh Token will expire you will renew them again by this request

• URL

  /renew

• Method:

  POST

• Header Params

  Authorization='Basic ' + btoa('client_id:client_secret_id)'

• Body Params(raw JSON) { "grant_type": "refresh_token", "refresh_token": "a6332349d0eb240b26f03a53ec12ad12d53ab90b" }

• Success Response:

  • Code: 200
    Content: { "access_token": "199146e7e010ffa216301333b4c8cc14b9184958", "accessTokenExpiresAt": "2020-03-24T13:34:07.337Z", "scope": "profile", "refreshToken": "1dcabd1c75520b4b8567517fc8cd0a8e218865b2", "refreshTokenExpiresAt": "2020-04-24T21:21:56.017Z" }

• Error Response:

  • Code: 400
    Content: { "statusCode": 400, "status": 400, "code": 400, "message": "Invalid grant: refresh token is invalid", "name": "invalid_grant" }

  • Code: 400
    Content: { "statusCode": 400, "status": 400, "code": 400, "message": "Invalid client: cannot retrieve client credentials", "name": "invalid_client" }

  • Code: 401
    Content:
    { "statusCode": 401, "status": 401, "code": 401, "message": "Invalid token: refresh token has expired", "name": "invalid_token" }

• Sample Call:

      //js
        var xhr = new XMLHttpRequest();
        var renewTokenURL = "http://brambleapi.herokuapp.com/renew";
        xhr.open('POST',renewTokenURL, true);
        xhr.setRequestHeader("Authorization","Basic "+ btoa("mansim:armygrid"));
        xhr.setRequestHeader("Content-Type", "application/json"); 
        var data = JSON.stringify({ "grant_type": "refresh_token","refresh_token": "5ce62efd36a7396abe79e8324bb65f5e33804859"});
        xhr.onreadystatechange = function() {
  
        if (xhr.readyState == XMLHttpRequest.DONE) {
                alert(xhr.responseText);
            }
        }
  
        xhr.send(data);        
  

      //request module nodejs
      var postData = {  
      "grant_type": "refresh_token",
      "refresh_token": "a6332349d0eb240b26f03a53ec12ad12d53ab90b"
      }
  
    var options = {
      url: 'http://brambleapi.herokuapp.com/grant',
      method: 'POST',
      headers: {
      "Authorization":"Basic " + btoa("mansim:armygrid")
      },
      body:postData,
      json:true
    };
  
    function callback(error, response, body) {
      if (!error && response.statusCode == 200) {
        console.log(body.accessToken);
        console.log(body.refreshToken)
      }
      else{
        console.log(body);
      }
    }
  
    request(options, callback);
  

• Notes:

  Using the old refresh Token you can regenerate new Refresh Token and new Access Token again. Refresh Token as it is called is used to refresh or renew tokens.

5. Returns the total bramble reals in the wallet.

---

To read the total amount of bramble reals in the user's wallet.

• URL

  /wallet_brambles_reals

• Method:

  GET

• Header Params

  Authorization='Bearer ' + access_token_received_in_grant_request

• Success Response:

  • Code: 200
    Content: 80.35

• Error Response:

  • Code: 401
    Content:
    { "statusCode": 401, "status": 401, "code": 401, "message": "Invalid token: access token has expired", "name": "invalid_token" }

  • Code: 401
    Content:
    { "statusCode": 401, "status": 401, "code": 401, "message": "Invalid token: access token is invalid", "name": "invalid_token" }

• Sample Call:

        var xhr = new XMLHttpRequest();
        var walletBrambleRealsURL = "http://brambleapi.herokuapp.com/wallet_brambles_reals";
        xhr.open('GET', walletBrambleRealsURL, true);
        xhr.setRequestHeader("Authorization","Bearer "+ "199146e7e010ffa216301333b4c8cc14b9184958");
        xhr.onreadystatechange = function() {
  
        if (xhr.readyState == XMLHttpRequest.DONE) {
                alert(xhr.responseText);
            }
        }
  
        xhr.send();
  

6. Sends bramble reals earned to the wallet.

---

To send the amount of bramble reals in the user's wallet.

• URL

  /send_brambles_reals/:reals

• Method:

  GET

• URL Params

  Required:

  reals=[Integer] (example: '4')

• Header Params

  Authorization='Bearer ' + access_token_received_in_grant_request

• Success Response:

  • Code: 200
    Content: success

• Error Response:

  • Code: 401
    Content:
    { "statusCode": 401, "status": 401, "code": 401, "message": "Invalid token: access token has expired", "name": "invalid_token" }

  • Code: 401
    Content:
    { "statusCode": 401, "status": 401, "code": 401, "message": "Invalid token: access token is invalid", "name": "invalid_token" }

  • Code: 500
    Content:
    error

• Sample Call:

        var xhr = new XMLHttpRequest();
        var sendBrambleRealsURL = "http://brambleapi.herokuapp.com/send_brambles_reals/10";
        xhr.open('GET', sendBrambleRealsURL, true);
        xhr.setRequestHeader("Authorization","Bearer "+ "199146e7e010ffa216301333b4c8cc14b9184958");
        xhr.onreadystatechange = function() {
  
        if (xhr.readyState == XMLHttpRequest.DONE) {
                alert(xhr.responseText);
            }
        }
  
        xhr.send();
  

7. Handles transfer of Bramble reals to game developer for shop items

---

Can be used for buying NPCs by the users and transfers the required amount to the developer's wallet.

• URL

  /handle_shop_reals/:reals

• Method:

  GET

• URL Params

  Required:

  reals=[Integer] (example: '4')

• Header Params

  Authorization='Bearer ' + access_token_received_in_grant_request

• Success Response:

  • Code: 200
    Content: success

• Error Response:

  • Code: 401
    Content:
    { "statusCode": 401, "status": 401, "code": 401, "message": "Invalid token: access token has expired", "name": "invalid_token" }

  • Code: 401
    Content:
    { "statusCode": 401, "status": 401, "code": 401, "message": "Invalid token: access token is invalid", "name": "invalid_token" }

  • Code: 500
    Content:
    error

• Sample Call:

        var xhr = new XMLHttpRequest();
        var buyNpcURL = "https://brambleapi.herokuapp.com/handle_shop_reals/4";
        xhr.open('GET', buyNpcURL, true);
        xhr.setRequestHeader("Authorization","Bearer "+ "199146e7e010ffa216301333b4c8cc14b9184958");
        xhr.onreadystatechange = function() {
  
        if (xhr.readyState == XMLHttpRequest.DONE) {
                alert(xhr.responseText);
            }
        }
  
        xhr.send();