Game API Documentation
Constructing Requests
Single API Requests
An example call to the API might look something like this:
https://api.gamejolt.com/api/game/v1_2/data-store/?game_id=32&key=test&signature=912ec803b2ce49e4a541068d495ab570
The above would return data stored in the system with the key of "test" for the game with the ID of "32".
It may look a little daunting at first, so let's dissect it.
Basic URL Construction
The first part is the URL of the Game API:
https://api.gamejolt.com/api/game/
Then comes the API version. The current version number is 1_2. This is to make sure old code still works, even if we change how the API works in the future.
https://api.gamejolt.com/api/game/v1_2/
The "data-store" part is the URL path that we use to retrieve an item from the data store.
https://api.gamejolt.com/api/game/v1_2/data-store/
(Look here for more information about the data store.)
Now we have to pass in some variables. This is done as simple GET query parameters. Note that you can also send the data through a POST method.
The variables required for each request can be found on their respective pages. Notice the "signature" parameter - this is required in every request to the system.
All variables except the signature value need to get URL encoded before passing them into the URL.
https://api.gamejolt.com/api/game/v1_2/data-store/?game_id=32&key=test&signature=912ec803b2ce49e4a541068d495ab570
Adding a Signature
Notice the "signature" parameter in the URL call above. The signature variable is a way to verify that the URL call came from you and not someone trying to crack the system.
First you need to form the URL that you want to query. For example, getting trophies for your game would be:
https://api.gamejolt.com/api/game/v1_2/trophies/?game_id=32&username=CROS&user_token=123456&achieved=true
Next, add the Private Key of your game (found under "Manage Achievements" on the game dashboard) to the end of the URL like so:
https://api.gamejolt.com/api/game/v1_2/trophies/?game_id=32&username=CROS&user_token=123456&achieved=truemy_awesome_private_key
Pump this string through either MD5
or SHA-1
and you have successfully generated a signature.
fc3e8e0ea54544b3551058f0cf524303
To finish up, add the signature to the original request URL.
https://api.gamejolt.com/api/game/v1_2/trophies/?game_id=32&username=CROS&user_token=123456&achieved=true&signature=fc3e8e0ea54544b3551058f0cf524303
Using POST data
All endpoints support submitting the variables in the POST data instead of GET query parameters.
This is convenient for many libraries and allows you to send longer requests which is especially useful with /batch/ requests.
The signature needs to be created differently when there is POST data.
We'll use a request to fetch the achieved trophies where the achieved
and user_token
variables are in the POST data as an example:
curl -XGET 'https://api.gamejolt.com/api/game/v1_2/trophies/?game_id=32&username=CROS' -d '
{
"user_token": 123456,
"achieved": "true"
}'
First, you take the GET part of the url, same as before:
https://api.gamejolt.com/api/game/v1_2/trophies/?game_id=32&username=CROS
Then, take the post data and join key/value pairs together without spaces in between in ascending alphabetical order by the key name.
So if we have user_token = 123456
and achieved = true
, the order of keys is achieved
and then user_token
so the resulting post data should look like this:
achievedtrueuser_token123456
Next, add the post data and the private key of your game to the end of the URL like so:
https://api.gamejolt.com/api/game/v1_2/trophies/?game_id=32&username=CROSachievedtrueuser_token123456my_awesome_private_key
Pump this string through either MD5
or SHA-1
and the signature is:
d1eefdaaa2cb35ee3ceac5ce11079c89
Lastly, add the signature to the original request URL and send it with the POST data:
https://api.gamejolt.com/api/game/v1_2/trophies/?game_id=32&username=CROS&signature=d1eefdaaa2cb35ee3ceac5ce11079c89
Arrays in POST Data
Some endpoints may have arrays in the post data, like the /batch requests[]
field. To make a signature for them, you would concatenate the key name with each one of the array values.
For example, when trying to make a signature for this:
curl -XGET 'https://api.gamejolt.com/api/game/v1_2/batch/?game_id=32&username=CROS' -d '
{
requests: [
'abc',
'def',
'ghi',
]
}'
The post data to sign would become requestsabcrequestsdefrequestsghi
, so the full url to sign would be:
https://api.gamejolt.com/api/game/v1_2/batch/?game_id=32&username=CROSrequestsabcrequestsdefrequestsghimy_awesome_private_key
To which the signature is:
d1387db85719d80afae538c5d5bca040