www.lucentinian.com

Highscores table web service and API


API

High scores tables can use the following operations:

Request authentication

We take your high score security seriously! Each request performed with our server must be authenticated using:

The table key and the password or shared secret are required to protect your data from spoofing or hacking.

Your requests will always be made using the HTTPS protocol, which provides encrypted communications from your game or application to our server.

Our authentication mechanism requires create a "fingerprint" of the data to be sent to our server. The fingerprint must be created based on:

Furthermore, it is required to append the length of the concatenation of all these data to calculate the fingerprint.

The fingerprint is calculated using the SHA256 algorithm to hash the data enumerated above.

The values for the hashed shared secret or password and the fingerprint are given as a lower case hexadecimal string.

As previously stated, the fingerprint must be calculated appending the current date and time. The server will deny requests that are one minute off from its date and time -- so if your high score record takes longer than a minute to send (this would only happen in rare cases), it will not work. In such case, store the record in local and retry later.

The data that we send from the game or application is concatenated using separators to avoid ambiguation. (We put the "|" character in the middle so that you can read it).

Here is how data fingerprints can be calculated:

string_to_hash <= uri "|" requestBody "|" timestamp "|" table_key "|" shared_secret

fingerprint <= SHA256( string_to_hash "|" string_length(string_to_hash) )

Check your framework documentation to see how to translate this into your desired syntax. We hope tha our demo, developed in Javascript, will be useful for testing. For example, Mozilla Firefox 30 is shipped with a web developer tool available in "Tools" -> "Web Developer" -> "Web Console" which can be used to inspect the packages which are sent from the demo to our server and the response.

Request header

The following fields must appear in each HTTPS request:

HTTP Requests

This section introduces, in detail, the operations that can be used with our API:

Get table

This is made using the GET verb. For example:

GET https://highscores.ehehdada.com/api/{table_name}?table_key={table_key} HTTP/1.1

Notice just putting the link above into your browser won't give you anything, because the strings "{table_name}" and "{table_key}" are just there as an example.

Path parameters:

Query parameters:

Request body:

The response is encoded in an array of high score records with the next JSON object structure:

NameTypeMandatoryDescription
scorenumericyesthe score which was recorded by the player
by_whomstringyesthe name of the player
when_happenednumericyesthe date time of this record in Unix format, from UTC time zone
ip4numericnoan unsigned integer with the IPv4 from your player's system
ip6numericnoan unsigned 128 bits integer with the IPv6 from your player's system
localestringyesthe locale of the player's device

For example:

Request:

GET https://highscores.ehehdada.com/api/test?table_key=test HTTP/1.1

Response:

[
  {"score":9999,"by_whom":"player#2","when_happened":2109020805,"ip4":3232235777,"ip6":null,"locale":"en-US"},
  {"score":123,"by_whom":"player#5","when_happened":2105951648,"ip4":3232235777,"ip6":null,"locale":"en-US"}
]

Check elegibility

This request is also made using the GET verb. In some cases, an application may need to check if a score will be above a certain rank on the high score table (if, for example, you only want the player to enter their name if they are in the top ten). There is one situation where trouble might arise. Let's say we only want to get the player's name if the player is ranked 10th in the table or better. Alice and Bob both rank 10th at the same time, and both enter their names at the same time. However, the server will handle one of their GET requests first. In this case, no error will occur. But it is wise, to check if the user's entered name and score are present after they enter their name.

GET https://highscores.ehehdada.com/api/{table_name}/check?score={score}&by_whom={by_whom}&table_key={table_key} HTTP/1.1

Notice just putting the link above into your browser won't give you anything, because the strings "{table_name}", "{score}", "{by_whom}", and "{table_key}" are just there as an example.

Path parameters:

Query parameters:

Request body:

The response is encoded an JSON object with the Boolean value 'is_elegible':

NameTypeMandatoryDescription
is_elegiblebooleanyesindicates if the given score is elegible to be inserted inside of the given high scores table

For example:

Request:

GET https://highscores.ehehdada.com/api/test?score=123&table_key=test HTTP/1.1

Response:

{"is_elegible":true}

Get server timestamp

If your game or application can't send any request because the clock of player's device is not correctly set up, you can request to our server to return its timestamp. This request doesn't need authentication.

GET https://highscores.ehehdada.com/timestamp HTTP/1.1

Path parameters:

Query parameters:

Request body:

The response is encoded an JSON object with the numeric value 'timestamp':

NameTypeMandatoryDescription
timestampnumericyesthe currect timestamp of our server in timezone independent or UTC

For example:

Request:

GET https://highscores.ehehdada.com/timestamp HTTP/1.1

Response:

{"timestamp":1406652098}

Add record

To insert a record into your high score table, you will need to use the POST verb. The server will accept the request if the given record effectively can be inserted in somewhere inside of the table, and it will return the position inside of the table as a numeric value. If the record was not successfully inserted, this request it will return a null value for the score's position.

POST https://highscores.ehehdada.com/api/{table_name} HTTP/1.1

Notice just putting the link above into your browser won't give you anything, because the string "{table_name}" is just there as an example.

Path parameters:

The request body is the record to insert encoded in JSON format:

NameTypeMandatoryDescription
scorenumericyesthe score which was recorded by the player
by_whomstringyesthe name of the player
when_happenednumericyesthe date time of this record in Unix format from UTC time zone
localestringyesthe locale of the player's device

The response is the field 'position' encoded inside of an JSON object:

NameTypeMandatoryDescription
positionnumericnoindicates the position inside of the highscores table where the record has been inserted, or null if it was rejected. A first place score will return 0, second place will return 1, etc.

For example:

Request:

POST https://highscores.ehehdada.com/api/test HTTP/1.1
timestamp: 1406652640397
tablekey: test
fingerprint: 9652d046366ff644aa30df7bf8b5143b73d2524445746d37ff03602ad79257d9
X-Requested-With: XMLHttpRequest
Content-Length: 83

{"score":"123","by_whom":"player#5","when_happened":1406652640694,"locale":"en-US"}

Response:

{"position":0}

Delete table (DEPRECATED)

Please be advised that this feature is deprecated and it will be removed from the API. It will be available in the future admin panel.

To delete your high score table and start over, you will need to use the DELETE verb.

DELETE https://highscores.ehehdada.com/api/{table_name} HTTP/1.1

Notice just putting the link above into your browser won't give you anything, because the string "{table_name}" is just there as an example.

As alternative for systems that do not support DELETE (for example, Unity), we have added the next alternative using GET verb instead:

GET https://highscores.ehehdada.com/api/{table_name}/deleted/ HTTP/1.1

This still requires the fingerprint field and the other headers listed in this API documentation.

Path parameters:

Request body:

This request doesn't return any body in the response.

For example:

Request:

DELETE https://highscores.ehehdada.com/api/test HTTP/1.1
timestamp: 1406652827374
tablekey: test
fingerprint: 41ebe0de2ba4c26551d91448abdf470a0ed19944cac9efd652baf3ef2b24960f
X-Requested-With: XMLHttpRequest

or

GET https://highscores.ehehdada.com/api/test/deleted/ HTTP/1.1
timestamp: 1419700348862
tablekey: test
fingerprint: 54988e72fa15175767f28036dd00e3c0aca9808137af7faa294b99a3f938bc8b
X-Requested-With: XMLHttpRequest

Response: N/A




Our Social Network links
[ Facebook ] | [ Google+ ] | [ LinkedIn ]

Copyright © 2014-2018 Lucentinian Works Co Ltd and ehehdada, ltd. All rights reserved.

Reproduction in whole or in part in any form or medium without express written permission of www.lucentinian.com is prohibited.