API Documentation

Game Jolt implements a RESTful API for accessing nearly every piece of data on our servers: games, news, comments, files, achievements, etc.

Calls to the system are done over the HTTP protocol, so nothing special is needed, and you can even test the service using a normal Web browser.

Sending Calls

An example call to the API might look something like:

http://gamejolt.com/service/games/

The above would return all the games in our system.

Multiple Formats

The API can return information currently in one of three formats:

xml

Returns information as XML. This is the default format if none is passed in.

json

Returns data as a JSON string.

simple

The Simple format returns "Success!" on success or a description of the error that occured on failure. The Simple format is usually used by game engines, that don't have XML or JSON parsing ability, to discern whether a certain request has succeeded or not (such as a user authentication).

To set which format to use in the response, you add a "format" query parameter and assign it the format you'd like. For example, the below request would return a listing of games in JSON.

http://gamejolt.com/service/games/?format=json

Resources

To access resources in the system, you simply pass in the correct URI. In the above examples we retrieved a list of games. If we would like to retrieve just one resource, we would place its ID on the end of the URL:

http://gamejolt.com/service/games/777/

The above URI would return the game with the ID of 777.

If we would like to retrieve a sub-resource from the system, such as a game's comments, we would pass in the name of the resource at the end of the url:

http://gamejolt.com/service/games/comments/

The above would return a listing of game comments. To retrieve a list of all the comments for a particular game, we would do something like the following:

http://gamejolt.com/service/games/777/comments/

The above would return a listing of the comments for the game with an ID of 777. To retrieve just one game comment, you would do something like:

http://gamejolt.com/service/games/comments/12/

The above would return the game comment with an ID of 12. As you can see, the system for accessing resources is very simple and very powerful.

Extra Query Parameters

You may want to pass in extra query parameters, instead of just an ID. Let's say you wanted to retrieve all adventure games in the system. That may look like so:

http://gamejolt.com/service/games/?genre=adventure

If you would like more information on the particular resources available, you can view the listing of resources in the top right box on this page.

Pagination

On each request to retrieve multiple resources, the system returns a section with the following information:

returned_rows

The number of rows returned.

total_rows

The number of total rows for the parameters passed in.

row_limit

The number of rows to return in each response. Its default value is 20. Its max value is 50.

page

The current page being returned. You can set this in the request to page through the results.

total_pages

The total number of pages for the parameters passed in based off of the number of rows to show per page.

You can use these returned parameters to page through the resources on our system.

You can override the row limit by specifying the "row_limit" parameter. Override the "page" parameter to set which page the API should return.

An example call using pagination may look like the following:

http://gamejolt.com/service/games/comments/?row_limit=5&page=2

The above would return 5 results per page and return the results for page 2.