Note: This post refers to the standard security workflow for GameOn Integration. For more information on the standard and advanced security options, click here.

In this post, I will demonstrate how to craft your first API calls with the tool Postman. Postman is a tool for developing and testing APIs, and is available as a Windows, Mac, or Linux native client for free at https://www.getpostman.com. If you haven’t installed Postman, I recommend you do this step right away.

As you design your tournaments and plan your GameOn integration, you can also begin to familiarize yourself with how the GameOn API works. GameOn uses a RESTful API – this means that your game will communicate with the GameOn servers through HTTP requests such as GET and POST, the same data requests that browsers use on the web.

Benefits of REST APIs

HTTP calls are well supported across game engines and operating systems if you want to jump right into coding, but it can be helpful to make a few test calls so you can see what format the request and replies are in.

Once you have Postman installed and have the API keys for a standard security game, here’s how to create a Register Player API call.

Getting started

First, create a new API request in Postman:

Save it with a descriptive name:

Go to the New Tab for the request. Change the request type from GET to POST and enter as the request URL:

https://api.amazongameon.com/v1/players/register

Next, open up the Headers tab and enter the following two keys and values:

Key                        Value

Content-Type          application/json

X-Api-Key               [the key labeled “Public API”]

The request should look like this:

Now switch to the Body section, select “raw," and enter the following text into the text field (I just used the “advertisingId” value from the documentation, you can use whatever ID or identifier you want, if any):

{
 "advertisingId" : "54d8fd8d-e349-49d8-902c-0558365ac22b"
}

Finally, click Send, and if all goes well, you should get a response at the bottom that looks like this:

You’ve just created your first GameOn REST API call! This response contains the player token and external player ID that associates this player with this game. In an actual game you would save these values with your player information for authenticating in game, but here, we’ll just copy the playerToken and craft the authentication step in Postman.

Authenticating

Players only need to be registered once, but authenticating needs to be done for every player session. You will use the player tokens you received from the registration call and do an authentication.

In order to do this, we will be making an Authenticate Player call. Add a new tab in Postman (don’t forget to save the request and give it a descriptive name), and, similar to the Register Player call, change the request to POST and enter the new URL:

https://api.amazongameon.com/v1/players/auth

Use the following headers:

Key                        Value

Content-Type          application/json

X-Api-Key               [the key labeled “Public API”]

You will then send the “playerToken” value received earlier in the body, along with advertising ID, player name, and some other information. There are several optional parameters that we’ll ignore:

{
 "advertisingId" : "54d8fd8d-e349-49d8-902c-0558365ac22b",
 "playerToken" : "",
 "playerName" : "",
 "deviceOSType" : "iOS",
 "appBuildType" : "development"
}

And, once again, if all goes well, you should see something like this:

Watch my webinar to learn more

Congratulations! You have now successfully registered and authenticated a player on GameOn.

From here, you can create additional API calls to try the other interfaces, as well as test the Admin API functions.

I’ve just scratched the surface of what Postman can do, but I’ve found it to be an invaluable resource during GameOn integration to debug my REST calls or even just to prototype a use case. I’ve also found it particularly useful to double-check what the API request or response actually looks like on the live servers.

You can get started now by visiting us at developer.amazon.com/gameon. If you’re interested in learning more about this process, watch my webinar below.