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

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.
the Manage API screen under the 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

An image showing a successful authentication request via the Postman application.

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.

Image of a valid "list environments" request 

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.