WebService API Quick Start
Last Updated

This article will help you quickly start developing using our WebService API.

It contains the basic concepts used in our REST API, as well some examples to quickly get you programming:

Responses

All responses are in standard JSON format.

Errors

Errors will still return a JSON document, with an adequate HTTP status set. The status is reproduced in the json response for ease of use.

Most errors will have the following structure:

{
    "detail": "This message explains what went wrong",
    "http_status": 403,
    "code": "permission_denied"
}

Forward Slashes in URLs

Always end the path portion of the URL with a forward slash.

GOOD

https://sandbox.vgjournal.net/api/games/super-mario-bros/

BAD

https://sandbox.vgjournal.net/api/games/super-mario-bros

Types of Endpoints

The API contains 3 types of endpoints:

  • Open Resources

Require no authentication and can be freely fetched at any time. These endpoints are mostly read-only.

  • Owner Resources

Is owned by an user. These are usually pages like the Gamelist, Achievements or Gaming Sessions.

Read access to these endpoints is governed by the user's privacy option. If public, it can be fetched like an Open endpoint. Otherwise, being authenticated and having the correct authorization is required for accessing the resource.

Write access on these endpoints are only available when authenticated as the user that owns the resource.

  • Special

Special endpoints have their own rules, and will often return responses with no body.

Pagination

Most endpoints in the API are paginated and have the following structure:

{
    "count": 42,
    "next": "...",
    "previous": null,
    "results": [
        ...
    ]
}

Where

  • count is the number of resources found in the endpoint.
  • next is the fully-formed, absolute URL to the next page. If null, the current page is the last.
  • previous is the fully-formed, absolute URL to the previous page. If null, the current page is the first.
  • results are json objects representing the endpoint's resources.

Endpoints that are not paginated will return all their results in a single array in the root of the JSON document:

[
    {
        ...
    },
    {
        ...
    },
    ...
]

Examples

  • Open Resource
  • Paginated

Code

import pprint
import requests

url = 'https://sandbox.vgjournal.net/api/search/'
params = {
    'q': "Zelda",
    'category': 'games',
}
response = requests.get(url, params)
pprint.pprint(response.json())

Result

{
    "count": 230,
    "next": "https://sandbox.vgjournal.net/api/search/?category=games&page=2&q=zelda",
    "previous": null,
    "results": [
        {
            "uuid": "b9211898-30b5-4a64-b9a5-469a6475faec",
            "cname": "the-legend-of-zelda",
            "name": "The Legend of Zelda",
            "help_text": "1986",
            "release": "1986-02-21",
            "restricted": false,
            "platforms": [
                "nes",
                "gba"
            ],
            "icon": null,
            "cover_thumbnail": null
        },
        {
            "uuid": "9600fe25-9b08-4db4-ad24-08077cf96e6c",
            "cname": "zeliard",
            "name": "Zeliard",
            "help_text": "1987",
            "release": "1987-12-19",
            "restricted": false,
            "platforms": [
                "msdos"
            ],
            "icon": null,
            "cover_thumbnail": null
        },

        ...

    ]
}

Example 2: Authenticate

  • Special

Code

import requests
import pprint

url = 'http://sandbox.vgjournal.net/api/auth/'
params = {
    'username': 'demo',
    'password': 'demo',
}
response = requests.post(url, params)
pprint.pprint(response.json())

Result

{
    "access": "...",
    "refresh": "..."
}

Example 3: Gamelist

  • Owner Resource
  • Unpaginated

Code

url = 'http://sandbox.vgjournal.net/api/users/demo/gamelist/'
access_token = 'example-access-token-that-does-not-work-please-retrieve-your-own-token-from-the-auth-endpoint'
headers = {
    'Authorization': 'Bearer ' + access_token,
}
response = requests.get(url, headers=headers)
pprint.pprint(response.json())

Result

[
    {
        "id": 1,
        "uuid": "c0659d2e-8f59-44d0-ba4c-30237aaa5145",
        "game": {
            "cname": "warhammer-40000-chaos-gate-daemonhunters",
            "name": "Warhammer 40,000: Chaos Gate - Daemonhunters",
            "sort_name": "warhammer40000chaosgatedaemonhunters  __autosortname__",
            "boxart": "https://sandbox.vgjournal.net/media/uploads/games/images/2022/11-November/25/thumbnails/warhammer-40000-chaos-gate-daemonhunters__cover__steam_tall.thumbnail.webp"
        },
        "status": "playing-occasionally",
        "platform": "win",
        "box_type": null,
        "bundle": null,
        "category": null,
        "comments": null,
        "completion": null,
        "condition": null,
        "edition": null,
        "favorite": false,
        "finish_date": null,
        "has_box": null,
        "has_manual": null,
        "hidden": false,
        "media_type": null,
        "playtime": 0,
        "priority": 0,
        "purchase_currency": null,
        "purchase_date": null,
        "purchase_value": null,
        "region": null,
        "score": null,
        "start_date": null,
        "times_completed": null,
        "vendor": null,
        "extra_data": null,
        "created_on": "2022-12-06T01:46:21.441185+00:00",
        "updated_on": "2022-12-06T01:46:21.441185+00:00"
    },
    ...
  ]

Hopefully that will have been enough to get you started with our RESTful WebService API.

More information for each Endpoint is available in their respective pages in the Browseable API (thought the documentation is far from complete).

In case this documentation isn't enough, or if you have any questions, feel free to reach us in the Support > developers channel of our discord, or using the website's Contact page.

Previous
Introduction to our RESTful WebService API
Settings
Developers
Other