Introduction to the Platform API
As part of our efforts to streamline the usage of the deltaDNA platform for our power users, we’ve begun making parts of the platform functionality accessible via a new RESTful API.
This article will serve as an introduction to the API’s function, and its technical documentation.
Requirements
In order to start using the API from scratch, you’ll need the following
- a deltaDNA account with one or more games
- “Account Owner” permissions for the account
- a REST client (such as Restlet or Postman)
- the Platform API Reference Manual on Swagger
Key creation
Before you can connect to the API, you will need to create a Key and Password within the platform.
You can do this
If you’re unfamiliar with OAuth terminology, this can be likened to signing up for a cinema’s unlimited movies service.
This is done by the Manage API screen, accessible from the account overview page’s “Account” menu.
This screen will show you any existing keys, and the “Create API Key” button.
Clicking that button will let you name the key, assign a password for the key, and choose which games and environments the API key will have access to.
Token acquisition
For those unfamiliar with OAuth, we use the credentials for the key against an authorisation endpoint which returns a token. Continuing our metaphor, even though we have an unlimited movie pass, we still need to get a ticket from the box office before we can go in.
Using our REST client we will create a POST request targeting the Authentication endpoint. The request has one header
key | value |
---|---|
‘Content-Type’ | ‘application/json’ |
The body of the request is a JSON object with two key-value pairs
key | value |
---|---|
‘key’ | the 32 character GUID |
‘password’ | the matching password |
The request returns a JSON object with two values, one is the token itself, which should be saved for future use.
The second is the expiration of the token, after which it will be necessary to acquire a new token with your API key & associated password.
Using the token
In this example, we’ll get a list of all the environments this key has access to, as a means of verifying everything is working correctly.
The endpoint for that is listed in the Swagger documentation here. There are no parameters, but with all requests using the API we need to send the token in the headers.
key | value |
---|---|
‘Authorization’ | ‘Bearer ’ & token |
We prefix the token’s value with the word “Bearer “. Noting the capital B and trailing space.
The response from this is a long list of all of the different environments we’ve been granted, in he form of an array of JSON objects.