This guide shows you the basics of using the Dinogen Online API and gives some examples of usages.
Introduction
The purpose of this guide is to help you use the Dinogen Online API to create any sort of 3rd party app that will support the Dinogen Community!
API Explanation
The API is used through a web request format. The base address can change from time to time, but it will always be like this: apiAddress/api/getCall?params. An example for getting a player’s data would be this. If you click on this link you will notice it returns a JSON. All API calls return a JSON. If you are unfamiliar with the JSON style of data storage, check out W3Schools Explanation. In order to work with this API you will need a basic knowledge of fetching from a web request server, JSON formatting, and JSON manipulation.
Making a fetch call
Once you have all the basic knowledge, its time to make your first fetch call. For the sake of simplicity I am going to give examples via JavaScript. Note that fetching files from web servers might be different depending on the programming language and the platform you are using.
To start a fetch call in JS you will need to start with a async function, like so:
async function getPlayerData(address, uname) { }
Note that this function has two parameters, address and uname. address gives the function the current API address (this will be discussed later), while uname gives the function the username of the player whos data you wish to retrieve.
Next, let’s add a fetch call and its dependents:
async function getPlayerData(address, uname) { fetch(address + 'api/getPlayer?username=' + uname).then( function (response) { return response.json(); }).then(function (obj) { console.log(obj); doStuff(obj); }).catch(function (error) { console.error(error); }); }
Woah, thats a lot to take in. Lets break it down. First, we call the built in JS function “fetch”, with the address we want to fetch from. Notice this address starts with the param “address”, has the string ‘api/getPlayer?username=’ in the middle, and the “uname” param at the end. That middle part is where the important parts happen. The “api/” is another part of the address that currently isnt in the address.txt file (more on that later). “getPlayer” is the name of one of the calls, specifically the one that returns a player data JSON (you can see all of the calls here). And “?username=” is one of the parameters required for the call. This is the basic setup for all the fetch calls to the API that you will make.
After that we call 3 different generic functions. The first translates a response into a readable JSON, and returns it to the second generic. The second logs the JSON object (which is basically the same as a JS object), then calls a function with that data, where you do whatever you need to with that data. The final generic catches any errors and logs them to the console.
Now that you have this, its time to make your fetch function work even when the main api address is down.
Accessing the API address
This portion is super simple. We use almost the same function as before:
async function getAddress(uname) { fetch('https://xwilkinx.com/data/dinogen/account.txt').then( function (response) { return response.text(); }).then(function (obj) { console.log(obj); getPlayerData(String(obj), uname); }).catch(function (error) { console.error(error); }); }
This time though, we go to a different address, and we translate the response to a string instead, and send this along to the function made earlier. Once this is all complete your system will update the address when a change is made. Now lets move on to doing things with this data.
Doing things with the data
Here is where we will do stuff with the data. Let’s start by filling out the function from before:
function doStuff(data) { var user = document.createElement('h1'); user.id = "user"; document.getElementById('dataDiv').appendChild(user); }
Here we create a element and add it to the DOM. This will display our requested username. Let give it some data:
function doStuff(data) { var user = document.createElement('h1'); user.id = "user"; user.innerHTML = data.username; document.getElementById('dataDiv').appendChild(user); }
If you are not familiar with dot notation, in this case it denotes object hierarchy. For example, data.username means that you want the value for the key “username”. This is the same as data[‘username’]. Another example is data.data.level. Now we add another layer to the hierarchy. We are asking for the value of the key “data”, which is another object, and then we ask for the value of the key “level” which is a integer. This is the same as data[‘data’][‘level’]. With this, it is super simple to access all the data in any JSON the API returns, as long as you know what you are grabbing.
Examples
Currently, there are two examples of usages of the API. The first is a stat checking website[ that is a work in progress, being made by yours truly. The second is a bot on the Dinogen Online discord[, which was made by Justin, the developer of Dinogen Online.
If you have any questions or issues with the API feel free to contact me or Justin on the discord!