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
Example 1: Search
- 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 |