API DOCS v1.1
Documentation for the API of iDev Games HTML5 Game PlatformGetting Started
Introduction
Welcome to the iDev Games API documentation. I will attempt to teach you about the API so that even if you don't know what an API is you should by the end and should be able to see it in action as you go along.
Our API is different to others and incase you skip parts I will make it clear now that the API works in conjunction with our web application "Game DB" although I will explain more about that in the comming sections.
I will be explaining everything in Javscript examples as although many will use either a library or a framework for their game if you do not use an engine.
I felt that Javascript would be the easiest to translate from. All examples will be editable and you can run an example at anytime while reading this documentation. Now the important thing to note about the examples is that they will all likely need to be edited. You will have to add your access token to each request and edit parameters etc that need to reflect your games "Game DB".
Regardless of language or game engine, I believe even developers who have only had experiance with visual game development and no coding or programming experiance will be able to edit the code examples and see them work. I believe it'll be a better way to learn.
This is a very exciting feature to iDev Games and I'm really looking forward to seeing what you do with the API. I've tried very hard to make this as easy to use as possible but with as much control as possible.
If you find an issue, have a question, find a spelling mistake or need some help message me on twitter @HTML5Arcade!
Let's begin!
What is an API?
API stands for application programming interface. It's basically the way you are able to work with features from our site externally through your games code. In some cases an API may allow you to access features from your account of the website or platform. So your account information can be used through another site or application.
Although in our case our API is designed slightly differently. Instead of the API being tied to your account, it is instead tied to your game. Allowing you to control your API through Game DB.
What is Game DB?
Game DB is your admin panel for the API. It's a web application that uses the API which is designed to make it easy to design a database for your game.
Allowing your players to have their own accounts. Giving you the ability to build your own MMO or make simple cloud saves. It can be as simple or as complex as you need it to be.
Best of all the ability to authenticate a login, create a new user or to change password through email all through simple requests to the API.
Game DB can be accessed through your game edit page. You will have to create a game here first.
How to access your API?
To access your API you must make your requests to the URL below:
https://idev.games/api/
All requests made will need to have this as the base URL with the specified endpoint added to the end of the URL. So for instance let's try the test endpoint below. Unlike the other endpoints this is a test and doesn't require any authorisation:
test
Responses
These are the responses you can expect to receive depending on the outcome. Hello WorldExample
See how in this javascript example.There's no better place to start then with "Hello World" for our first request. As you can see in the Javascript that there is "var url". That is the URL the request is being made to. After the getting started section the rest of the documentation will look like the endpoint example above.
How to authorise your requests?
As mentioned in the previous example. The first test didn't need any authorisation, that's because it was a test just to show you how you can access the API.
For actual requests you will need to be authorised to do so. Just like the example above we are going to do the same again but this time with authorisation. So the next endpoint will be one that requires your API auth token.
But first, you need to retrieve your auth token from your game edit page. When editing a game scroll down the page until you find the "Your API Keys" section like below:
By clicking Reveal Auth Token and entering your password. You will then be given access to your auth token. Now copy your auth token and try the example for the get/authtest endpoint below:
authtest
Responses
These are the responses you can expect to receive depending on the outcome. Success UnauthorizedExample
See how in this javascript example. You will need to add your auth token to the auth_token variable for the test to work.How do I keep the API secure?
Security is a real issue when it comes to HTML5 games. As HTML5 is a front end technology, all code is sent to the user for the browser to then render. This means variables and logic including the use of API keys are all accessible to anyone.
This is an issue when using APIs within HTML5 games. So to try and make our API as secure and as accessible as possible, the API will only work in a read only state until a user is authenticated. Allowing for only user data to be edited through the API. Any global data must be set through Game DB and I will explore the ways to automate jobs for the global data later down the road to have the ability of something like global time etc. Which means if someone was to try and use your API key they would only be able to read data unless they logged in and authenticated their requests which would only effect their account.
Although that being said cheating is something that cannot be prevented, try to be obscure with the way data is saved to try and make it harder for those trying to cheat or use any other cheat deterrents where possible.
Never save any personal data. Personal data should never be needed and if saved will then be accessible through the API. An email address is taken for a user when an account has been created which is used for resetting passwords and logging in. The email address is not accessible through the API or Game DB to keep the email address secure.
As Game DB is required to have a lot more power then the API used in your game, always make sure to lock Game DB when you are finished before closing Game DB down. By doing this the access will be revoked and only a successfull login back into Game DB will open access again.
Important information about deleting data
It's important to understand how the system will deal with the deletion of data. First off some will know of soft deletes and hard deletes and if not then I will explain these two concepts quickly. Basically a soft delete is where data is marked as no longer used within the database but still actually exists. This is very popular for websites as this minimises the risk of anything going wrong and allows data to be brought back.
Hard deletes is where the actual data is removed from the database permanently. Meaning it is gone for good and you won't be able to retrieve this data.
Now it is important to understand that all data through the API when deleted is hard deleted. There is no way to get it back. When you remove users, all the rows that user have added to your tables will be deleted too. So be very careful when you remove users, tables, columns or rows through Game DB as you won't be able to retrieve this data again period.
The same goes for when you use the API end points for removing users rows. You can build your own soft delete system by not bringing back data marked as removed within a column, although it is up to you to do this.
This is done to try and keep our DB cleaner and smaller.
USERS >