Documentation - Game Score - Just add a game...

Index

API calls
URL construction
1. startSession
2. addScore
3. getHighScore
4. registerWithScore *
5. endSession
Status Codes

General

API calls

Game-Score API has 2 different endpoints - one for testing (sandbox) and one for production usage. The testing one is located at http://game-score.net/apisandbox/. The databases of sandbox endpoint is sanitized on a daily basis and each client is capable to set the exact time for this operation.
The production endpoint is located at http://game-score.net/api/. All the data collected via this endpoint is stored permanently, so be careful with its usage. Development and testing should be done using sandbox mode and moved to production mode once the application is ready.

Game-Score API can be called either POST or GET. It also support XML and JSON protocols. The server-side will automatically recognize request properties and the response will be the same method and type.

POST JSON Request

Method	URL
POST	api/json/

GET JSON Request

Method	URL
GET	api/json/

URL construction

The URL construction is used to format the service communication. Next to api/ is the protocol descriptor JSON /json/ or XML /xml/.At the end comes the called API method. Parameters need to be passed in respect to the used request method. For GET request parameters are passed as URL_PARAM

Request

Method	URL
GET	api/json/methodName

Methods

1. startSession

Initialize new session. There will be returned session ID with the response. Used to track how many games are played in one session. It should be started right after the app is started.

Request

Method	URL
GET/POST	api/json/startSession/ api/xml/startSession/

Type	Params	Values
var	appId	string

appId
appId must be sent with all client requests. The appId can be obtained from games section of the Back Office and helps the server to validate the request source.

Response

Status	Response
200	`{ "success": , "sessionid": }`
403	`{"error":"API key is missing."}`
401	`{"error":"Invalid API key."}`
500	`{"error":"Something went wrong. Please try again later."}`

2. addScore

Adds new score to the scoreboard. If highscore is set to If true, there will be returned high score list with the response.

Request

Method	URL
GET/POST	api/json/addScore/ api/xml/addScore/

Type	Params	Values
var	appId	string
var	sessionid	string
var	score	number
var	nickname	string [optional] [default “Player”]
var	highscore	boolean [optional] [default false]
var	limit	number [optional] [default 10]
var	playerRank	boolean [optional] [default false]

appID
appID is obtained from the service Back Office

sessionid
sessionid is obtained from the startSession API method /api/json/startSession

score
The score achieved by the player

nickname
Player nickname; Optional; Default value will be “Player”

highscore
Boolean to define if highscores should be returned or not; Optional; Default value will be false

limit
Limit the amount of the returned highscores; Optional; Default value will be 10

playerRank
Boolean to define if current player rank should be returned if it is not in the given limit; Optional; Default value will be false

Response

Status	Response
200	Response will be an object containing the list of highscores. `{ "success": true, "highscorelist": { {"rank":1, "nickname":"Player", "score":1000}, {"rank":1, "nickname":"Player", "score":1000}, ... {"rank":1, "nickname":"Player", "score":1000} } }`
400	`{"error":"Missing parameter."}`
401	`{"error":"Invalid API key."}`
500	`{"error":"Something went wrong. Please try again later."}`

3. getHighScore

Returns high score with paging. Page size is defined by the limit parameter and the start parameter is used for getting next page.

Request

Method	URL
GET/POST	api/json/getHighScore/ api/xml/getHighScore/

Type	Params	Values
var	appId	string
var	limit	number [optional] [default 10]
var	start	number [optional] [default 0]

appID
appID is obtained from the service Back Office

limit
Limit the amount of the returned highscores; Optional; Default value will be 10

start
Defines the first highscore to be returned; Optional; Default value will be 0

Response

Status	Response
200	Response will be an object containing the list of highscores. `{ "success": true, "highscorelist": { {"rank":1, "nickname":"Player", "score":1000}, {"rank":1, "nickname":"Player", "score":1000}, ... {"rank":1, "nickname":"Player", "score":1000} } }`
400	`{"error":"Missing parameter."}`
401	`{"error":"Invalid API key."}`
500	`{"error":"Something went wrong. Please try again later."}`

4. registerWithScore *

Registers a player achievement with possibility to record first and last name, an e-mail and telephone.
The user data is not mandatory so everyone decide if they should be captured. None of these data will be used from API Creator in any way.
* this method is available in “simple game +”

Request

Method	URL
GET/POST	api/json/registerWithScore / api/xml/registerWithScore /

Type	Params	Values
var	appId	string
var	sessionid	string
var	score	number
var	nickname	string [optional] [default “Player”]
var	firstname	string [optional]
var	lastname	string [optional]
var	email	string [optional]
var	phone	string [optional]
var	highscore	boolean [optional] [default false]
var	limit	number [optional] [default 10]
var	playerRank	boolean [optional] [default false]

appID
appID is obtained from the service Back Office

sessionid
sessionid is obtained from the startSession API method /api/json/startSession

score
The score achieved by the player

nickname
Player nickname; Optional; Default value will be “Player”

firstname
Player firs tname; Optional; First name of the player

lastname
Player lastkname; Optional; Last name of the player

email
Player email; Optional; Email of the player

phone
Player phone; Optional; Phone of the player

highscore
Boolean to define if highscores should be returned or not; Optional; Default value will be false

limit
Limit the amount of the returned highscores; Optional; Default value will be 10

playerRank
Boolean to define if current player rank should be returned if it is not in the given limit; Optional; Default value will be false

Response

Status	Response
200	Response will be an object containing the list of highscores. `{ "success": true, "highscorelist": { {"rank":1, "nickname":"Player", "score":1000}, {"rank":1, "nickname":"Player", "score":1000}, ... {"rank":1, "nickname":"Player", "score":1000} } }`
400	`{"error":"Missing parameter."}`
401	`{"error":"Invalid API key."}`
500	`{"error":"Something went wrong. Please try again later."}`

5. endSession

Closes current session. Should be used on app exit.

Request

Method	URL
GET/POST	api/json/endSession/ api/xml/endSession/

Type	Params	Values
var	appId	string
var	sessionId	string

appId
appId must be sent with all client requests. The appId can be obtained from games section of the Back Office and helps the server to validate the request source.

sessionId
sessionid is obtained from the startSession API method /api/json/startSession

Response

Status	Response
200	`{ "success": , "sessionid": }`
400	`{"error":"Missing parameter."}`
401	`{"error":"Invalid API key."}`
500	`{"error":"Something went wrong. Please try again later."}`

Glossary

Example provided are with JSON protocol because of the better readability.

Conventions

Client - Client application.
Status - HTTP status code of response.
All the possible responses are listed under ‘Responses’ for each method. Only one of them is issued per request server.
All response are in JSON format.
All request parameters are mandatory unless explicitly marked as [optional]
The type of values accepted for a request parameter are shown the the values column like this [10|] .The | symbol means OR. If the parameter is [optional], the default value is shown in blue bold text, as 10 is written in [10|].

Status codes

All status codes are standard HTTP status codes. The below ones are used in this API.

2XX - Success of some kind
4XX - Error occurred in client’s part
5XX - Error occurred in server’s part

Status code	Description
200	OK
201	Created
202	Accepted (Request accepted, and queued for execution)
400	Bad request
401	Authentication failure
403	Forbidden
404	Resource not found
405	Method Not Allowed
409	Conflict
412	Precondition Failed
413	Request Entity Too Large
500	Internal Server Error
501	Not Implemented
503	Service Unavailable