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
- Code: 200
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" }
- Code: 200
Error Response:
- Code: 400
Content:{ "statusCode": 400, "status": 400, "code": 400, "message": "Invalid grant: authorization code has expired", "name": "invalid_grant" }
- Code: 400
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
- Code: 200
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" }
- Code: 200
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
- Code: 200
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
- Code: 200
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
- Code: 200
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();