gamejolt / doc-game-api

Game Jolt

This is the whole frontend for Game Jolt. It powers the site and the desktop app.

We wanted to make it open source so everyone can get visibility into what we are working on. Browse the code to see how Game Jolt is put together. Feel free to offer suggestions on how to do things better, as well as contributing your own code. I'll get a better guide on how to contribute soon.

Requirements

• Install NodeJS v16+
• Install Yarn
• Run in terminal:
  • git submodule init
  • git submodule update
  • yarn
• Install git pre commit hooks:
  • Windows (from administrator powershell): .\git-hooks\install.ps1
  • Mac / Linux: ./git-hooks/install.sh
• Add 127.0.0.1 development.gamejolt.com to your /etc/hosts (or C:\\Windows\\System32\\drivers\\etc\\hosts on Windows)
• Setup local development certificates.
  • Windows:
    1. Run scripts\certs\generate-cert.ps1.
    2. Open gamejoltCA.crt file it generated.
    3. Press "Install certificate" button.
    4. For "Store Location" leave it as "Current User" and hit "Next".
    5. Choose "Place all certificates in the following store" and hit "Browse"
    6. Choose "Trusted Root Certification Authorities" and hit "Ok"
    7. Restart your browser for changes to take effect.
  • Linux:
    1. Run ./scripts/certs/generate-cert.sh
    2. Add the cert to the local trust
       • On Ubuntu/Debian:

         sudo cp gamejoltCA.crt /usr/local/share/ca-certificates/gamejoltCA.crt
         sudo update-ca-certificates
         

       • On RHEL/Centos/Fedora:

         sudo cp gamejoltCA.crt /etc/pki/ca-trust/source/anchors/gamejoltCA.crt
         sudo update-ca-trust extract
         

  • Mac: TODO

Running

• Website

  Run yarn dev in the project directory.

  It'll set up a tiny server that hosts the website for you on your computer at https://development.gamejolt.com. Open that URL up in a web browser and you should have Game Jolt running!

  • Mac users will also have to forward traffic from port 8443 to 443 to get around a security restriction (see note below)

• Desktop app

  Run yarn client:dev in the project directory.

  In another terminal run yarn client.

  • Mac users will also have to forward traffic from port 8443 to 443 to get around a security restriction (see note below)

Note: First time running these will take longer than usual.

For more commands see COMMANDS.md.

Translations

Translations are done by the community. If you want to participate, feel free to join at https://poeditor.com/join/project/B4nWT6EgnD.

Notes for Mac Users

Listening on port 443 (the default port for https) requires root privileges, but we want to keep root usage to a minimum.

For this reason, the webserver listens on port 8443 instead, and then in a separate rooted process we can forward traffic from port 443 to port 8443.

There are plenty of ways to do that, personally I like using socat:

• Install using brew install socat
• Run the following while developing:

  sudo socat tcp4-listen:443,bind=127.0.0.1,reuseaddr,fork tcp:127.0.0.1:8443
  

doc-game-api's Issues

Batch POST misleading.

"Because the constructed URL can become quite lengthy, the entire request is sent via POST data. If the URL is not too long, you can send it via GET request as well."

This sentence is confusing. I think if it was changed so it said, "the entire request could be sent view POST data" instead. Basically, since the URLs can become lengthy, they can be sent via POST data. However, you're free to also pass it as GET.

Change gamejolt.com domain to api.gamejolt.com domain across all pages.

Unique scores not working properly

I've experienced a strange behavior with unique scores and as it seems I'm not the only one.
If I set "unique scores" to false, everything is working just fine, but if I set it to true, the api always returns no scores. Even the webinterface tells me that there are no scores, which is obviously incorrect, because there are tons of scores if I disable "unique scores".

A call to https://gamejolt.com/api/game/v1_1/scores?game_id=GameID&limit=10&format=json&signature=...
only returns {"response":{"success":"true","scores":""}}

Missing new Sessions#Check endpoint in version history

Unless this was present but undocumented in v1.0, it's Sessions#Check is new to me and should be added to the version history.

Sessions#Ping shows possible values for the wrong parameter

The title of the second table should read Valid Values for status

Sessions#Ping

All attributes of the GetTime response are singular except seconds

I don't know if that's a mistake in the documentation or a inconsistency in the implementation but year, month, day, hour and minute are all singular but seconds is plural.

Get Time

trophies api call returns malformed json

The trophies call returns a string starting with the letter 's' and followed by the expected json.
A call to https://gamejolt.com/api/game/v1_1/trophies?... will result in:

s{
    "response":{
        "success":"true",
        "trophies":[
            {
                "id":"12345",
                "title":"Bronze Trophy",
                "description":"I'm a bronze trophy.",
                "difficulty":"Bronze",
                "image_url":"...",
                "achieved":"false"
            }
        ]
    }
}

Sessions Check misuse the response's success key

When using Sessions Check, it will return {"success":true} when a session is open but {"success":false,"message":""} when there is no open session.

The success key should only be used to indicate whether the request succeeded or failed (like any other API call).

The result of the check should has its own key, e.g. check or has_session_open.

Cannot get rank! [SOLVED]

/scores/get-rank/ gives back the same response like /scores/.
It was supposed to give me a single number but instead I get a bunch of score objects.

[already solved!]

Formats should be lowercase

Formats should be lowercase. If you pass a non-lowercase format, the API does not return anything.

Based on my experience with the API v1.0, I don't know how v1.2 behave on that regard.

Data Store - Set restriction feature not working

Data entries set with the restriction feature are still overwritable by others.
User X sets a new item with this:
https://gamejolt.com/api/game/v1_1/data-store/set/?game_id=XXX&key=Test&restriction_username=USER_X&restriction_user_token=TOKEN_X&format=json&signature=XYZ (data is provided via POST)
This returns success and I can see the item in the data store, but others are still able to overwrite it:
https://gamejolt.com/api/game/v1_1/data-store/set/?game_id=XXX&key=Test&format=json&signature=XYZ (data is provided via POST)

Broken Links

On the index, the link to batch should be https://github.com/gamejolt/doc-game-api/blob/master/v1.x/batch/index.md

On the users index, the link to fetch should be https://github.com/gamejolt/doc-game-api/blob/master/v1.x/users/fetch.md

On the trophies index, the link to fetch should be https://github.com/gamejolt/doc-game-api/blob/master/v1.x/trophies/fetch.md

On the scores index, the link to fetch should be https://github.com/gamejolt/doc-game-api/blob/master/v1.x/scores/fetch.md

On the get-time index, the link to fetch should be https://github.com/gamejolt/doc-game-api/blob/master/v1.x/get-time/fetch.md

On the data-store index, the link to fetch should be https://github.com/gamejolt/doc-game-api/blob/master/v1.x/data-storage/fetch.md

Report whether a trophy is secret and/or hidden

The api does not report whether a certain trophy is secret or not. It also doesn't report if it is hidden.
To overcome this issue I currently use a local list of secret/hidden trophies to test against, of course it would be much more convenient if the api call just tells me if a trophy is secret/hidden or not.

Need to describe how each type of build gets passed username/token.

Each type of game/build gets passed username/token differently. We need to explain it all somewhere. It's really helpful to be auto-logged in while playing games on the site.

Examples for Users#Fetch are all over the place.

The example response is one line below what it should be.

First few lines of the Users#Fetch examples:

--- | --- | --- success | boolean | Whether the request succeeded or failed.
Example: true message | string | If the request was not successful, this contains the error message.
Example: No such user could be found. id | integer | The ID of the user.
...

"true" belongs to the first line with "success | boolean"
"No such user could be found" belongs to the second line with "message | string"
...

The URLs of Version 1.2 do not work! [SOLVED]

The /get-time/ example shows that the only thing you get is a blank page.
Same goes for /sessions/check/.

[Already solved]

Need examples for how the URL encoding is done in batch calls.

It's mentioned in batch/index, but it doesn't give examples. Since the URL encoding is pretty confusing (and possibly one of the most complicated bits of the whole process), I think it deserves some better step-by-step examples of how the URL transforms.

Backticks around parameter names.

DataStore#Update shows possible values for the wrong parameter

The title of the second table should read Valid Values for operation

DataStore#Update