REST APIs Overview

The GameSparks REST API is composed of two parts:

The Requests REST API, which you can use for your game's runtime environment.
The Management REST API, which you can use to set up all you game configuration and build out your game.

FAQs? You can review Frequently Asked Questions about working with the REST APIs.

Requests REST API

The Request REST API is provided for game's runtime:
Unlike the Management REST, this REST API is designed for server-to-server connections.

Further Details? For more details on the Requests REST API, see here.

Management REST API

The Management REST API is split into 4 components which can be used to configure all aspects of your game, as well as giving you access to your runtime data.

Important! The remainder of this page applies to the Management REST API.

Authentication

Acts as an identity provider.
Provides a JWT-based single sign-on solution.
Manages groups, collaborators, and permissions for all resources.
The base URL is: https://auth.gamesparks.net
Try it out here

Game Administration

Provides REST endpoints to perform actions on a Game that are not part of the game configuration itself.
Examples of this sort of action are: managing snapshots, managing admin screens, testing push notifications.
The base URL is: https://config2.gamesparks.net
Try it out here

Game Configuration

Provides all endpoints required to manage the game configuration that will be pushed to the runtime servers.
The base URL is: https://config2.gamesparks.net
Try it out here

NoSQL

An instance of this application is deployed in each runtime cluster.
Provides an interface into the game’s data stored in Mongo and Redis.
The base URL is not fixed but is dependent on the specific runtime cluster that your game is assigned to and the game stage - see Discovering the Endpoint on this page.
Try it out here

Architecture

The following high-level architecture diagram of the platform shows how these REST endpoints interact with other components:

There are 3 REST API server types:

Auth REST API server - handles the Authentication REST calls
Config REST API server - handles both the Game Configuration and the Game Administration REST calls.
NoSQL REST API server - handles the Runtime Data REST calls. An instance of this application is deployed on each runtime cluster.

REST API Requests Rate Limits

The rate at which you can submit requests against our REST API is limited as follows:

No more than 300 requests per user per minute.
No more than 600 requests per game per minute.

The rate at which you can submit game configuration update requests is also limited:

No more that 10 update requests at once for the same game/user.
This limit only apply to updates - POST, PUT, or PATCH - and not to GET requests. So you can only be doing 10 updates at once, but as many GETS as you want (subject to the other rate limits).

NOT APPLICABLE to Requests REST API! Note that these limits on request rate do not apply to the Requests REST API. The Requests REST API is subject to all the normal limits as stated under our Fair Usage Policy.

Exceeding REST Request Rate Limits? If you try to exceed these limits you will receive an error: 429 Too many requests.

Authorization Process

The Authentication Server determines whether or not a user is allowed to perform an action. Each time a REST request is made, the Authorization Process validates a user's credentials with the Authentication Server.

GameSparks supports 3 types of authentication:

Basic Authentication

You can use your portal credentials and provide an Authorization header:

This type of authentication works for the Authentication, Game Configuration and Game Administration endpoints.

GameSparks Access Token

This is a JSON web token that is generated by the Authentication server:

Use the X-GSAccessToken header to pass this token in.
A JSON web token is always validated against the Authentication server.
Unless otherwise specified, it has an expiry time of 1 hour.
In order to get this token you can do a GET https://auth.gamesparks.net/restv2/auth/user with basic authentication. Try it out here.
This type of authentication works for the Authentication, Game Configuration and Game Administration endpoints.

GameSparks JSON Web token

The JSON web token also contains information about the user's permissions for a game:

Use the X-GS-JWT header to pass this token in.
This is a JSON Web Token that also contains information about the user's permissions for a resource. That is why this token does not need to be validated against the Authentication server because it contains enough information to decide whether or not a user is allowed access to a resource.
Unless otherwise specified, it has an expiry time of 1 hour.
In order to get this token you can do a GET https://auth.gamesparks.net/restv2/auth/game/{apiKey}/jwt with basic authentication. Try it out here.
This token was designed for the NoSQL REST API, because the NoSQL REST server and the Auth REST API can be geographically far apart. However, it works with all 4 components of the GameSparks REST API.

You can find more details about the specification for JSON Web Tokens here.

Managing JWT Scope

Because an X-GS-JWT token contains all the permissions for a game, it can become quite large. If you know you are going to use the token for a single functionality, such as NoSQL, you can get a token the scope of which is smaller:

You can use this endpoint to get a scoped X-GS-JWT: https://auth.gamesparks.net/restv2/auth/game/{apiKey}/jwt/{filter}

Schema

All API access is over HTTPS.
All data is sent and received as JSON.
All dates and timestamps are returned in ISO 8601 format:


YYYY-MM-DD and YYYY-MM-DDTHH:MM:SSZ

HTTP Verbs

Verbs	Description
GET	Used for retrieving resources.
POST	Used for creating resources.
PUT	Used for updating resources.
DELETE	Used for deleting resources.

Status Code

Code	Description
200	OK
201	Created
400	Bad request
401	Token expired
403	Not allowed
404	Not found
429	Too many requests
500	Internal server error

Examples

Get Access Token

Request:

GET https://auth.gamesparks.net/restv2/auth/user
Authorization: Basic dXNlckBlbWFpbC5jb206cGFzc3dvcmQ=
Content-Type: application/json

Response:


{
  "country": "UK",
  "username": "user@email.com",
  "expiresAt": 1487345184073,
  "X-GSAccessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0ODczNDUxODQsImlkZW50aXR5IjoidXNlckBlbWFpbC5jb20ifQ.neJJnjlpXpYpCi7y6OK43oqELk6BNmKa1cC4JTZy4Z0"
}

Get JWT Token

Request:


GET https://auth.gamesparks.net/restv2/auth/game/J3335lNuVXGb/jwt
X-GSAccessToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0ODczNDUxODQsImlkZW50aXR5IjoidXNlckBlbWFpbC5jb20ifQ.neJJnjlpXpYpCi7y6OK43oqELk6BNmKa1cC4JTZy4Z0
Content-Type: application/json

Response:

{
  "username": "user@email.com",
  "expiresAt": 1487345848710,
  "X-GS-JWT": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJnYW1lSWQiOjMzMzUsImNvdW50cnkiOiJVSyIsImFwaUtleSI6IkozMzM1bE51VlhHYiIsInBlcm1pc3Npb25zIjp7IkozMzM1bE51VlhHYiI6eyJjb25maWd1cmF0b3IuaW50ZWdyYXRpb25zLnByb3ZpZGVycy5hbWF6b24iOjAsImNvbmZpZ3VyYXRvci5ldmVudHMucnVubmluZ1RvdGFscyI6MiwiY29uZmlndXJhdG9yLmdlb3Jlc3RyaWN0aW9ucyI6MiwiY29uZmlndXJhdG9yLnNjcmlwdHMucmVxdWVzdCI6MiwiYWRtaW4ucGVybWlzc2lvbnMuZ3JvdXBzIjoyLCJjb25maWd1cmF0b3IuYWNoaWV2ZW1lbnRzIjoyLCJhbmFseXRpY3MiOjIsIm1hbmFnZS5zbmFwc2hvdHMiOjIsImFkbWluLnNuYXBzaG90cyI6MiwiY29uZmlndXJhdG9yLmludGVncmF0aW9ucyI6MiwiY29uZmlndXJhdG9yLmdhbWUuZGVsZXRlIjoyLCJhZG1pbi5sb2dTdW1tYXJ5IjoyLCJjb25maWd1cmF0b3IuZ2FtZSI6MiwiY29uZmlndXJhdG9yLmludGVncmF0aW9ucy5wcm92aWRlcnMudHdpdHRlciI6MCwiY29uZmlndXJhdG9yLnNjcmlwdHMuaW1wb3J0IjoyLCJjb25maWd1cmF0b3IuZ2FtZS5jaGFuZ2VPd25lciI6MiwiY29uZmlndXJhdG9yLnNjcmlwdHMuc3lzdGVtTW9kdWxlcyI6MiwiY29uZmlndXJhdG9yLm11bHRpcGxheWVyLm1hdGNoZXMiOjIsImNvbmZpZ3VyYXRvci5zY3JpcHRzLnJ0TW9kdWxlcyI6MiwiY29uZmlndXJhdG9yLmludGVncmF0aW9ucy5wcm92aWRlcnMuYXBwbGUiOjAsIm5vc3FsIjoyLCJhZG1pbi5wdWJsaXNoIjoxLCJjb25maWd1cmF0b3IuaW50ZWdyYXRpb25zLnByb3ZpZGVycy5taWNyb3NvZnQiOjAsImNvbmZpZ3VyYXRvci5ldmVudHMiOjIsImNvbmZpZ3VyYXRvci5pbnRlZ3JhdGlvbnMucHJvdmlkZXJzIjoyLCJjb25maWd1cmF0b3IubWVzc2FnZXMiOjIsImNvbmZpZ3VyYXRvci5zY3JpcHRzLnVzZXJNZXNzYWdlIjoyLCJjb25maWd1cmF0b3Iuc2NyaXB0cy5jaGFsbGVuZ2VFdmVudCI6MiwiY29uZmlndXJhdG9yLmludGVncmF0aW9ucy5wcm92aWRlcnMud2VjaGF0IjowLCJjb25maWd1cmF0b3Iuc2NyaXB0cy5tb2R1bGVzIjoyLCJjb25maWd1cmF0b3IuaW50ZWdyYXRpb25zLnByb3ZpZGVycy5wc24iOjAsImNvbmZpZ3VyYXRvci5pbnRlZ3JhdGlvbnMucHJvdmlkZXJzLnN0ZWFtIjowLCJjb25maWd1cmF0b3IubXVsdGlwbGF5ZXIuY2hhbGxlbmdlcyI6MiwiY29uZmlndXJhdG9yLnNjcmlwdHMucnRTY3JpcHQiOjIsImNvbmZpZ3VyYXRvci5pbnRlZ3JhdGlvbnMucHJvdmlkZXJzLnFxIjowLCJhY2Nlc3MiOjIsImV4cGVyaW1lbnRzIjoyLCJhZG1pbiI6MiwiY29uZmlndXJhdG9yLm11bHRpcGxheWVyIjoyLCJhZG1pbi50ZXN0SGFybmVzcyI6MiwiY29uZmlndXJhdG9yLnRlYW1zIjoyLCJhZG1pbi5wZXJtaXNzaW9ucy5nYW1lIjoyLCJhZG1pbi5wZXJtaXNzaW9ucy5jb2xsYWJvcmF0b3IiOjIsImNvbmZpZ3VyYXRvci5pbnRlZ3JhdGlvbnMucHJvdmlkZXJzLnR3aXRjaCI6MCwiY29uZmlndXJhdG9yLmludGVncmF0aW9ucy5wcm92aWRlcnMua29uZ3JlZ2F0ZSI6MCwiYWRtaW4ubmV3RmVhdHVyZXMiOjIsImNvbmZpZ3VyYXRvci5pbnRlZ3JhdGlvbnMucHVzaFRlc3QiOjIsImNvbmZpZ3VyYXRvci52aXJ0dWFsR29vZHMiOjIsImNvbmZpZ3VyYXRvci5pbnRlZ3JhdGlvbnMucHJvdmlkZXJzLmdvb2dsZSI6MCwiY29uZmlndXJhdG9yLnNjcmlwdHMuZXZlbnQiOjIsImNvbmZpZ3VyYXRvci5jcmVkZW50aWFscyI6MiwiY29uZmlndXJhdG9yLmdhbWUuZGV0YWlscyI6MiwiYWRtaW4ucGVybWlzc2lvbnMiOjIsImNvbmZpZ3VyYXRvci5jdXJyZW5jeTYiOjAsImNvbmZpZ3VyYXRvci5jdXJyZW5jeTUiOjAsImNvbmZpZ3VyYXRvci5jdXJyZW5jeTQiOjAsImNvbmZpZ3VyYXRvci5jdXJyZW5jeTMiOjAsImNvbmZpZ3VyYXRvci5jdXJyZW5jeTIiOjAsImNvbmZpZ3VyYXRvci5jdXJyZW5jeTEiOjAsImNvbmZpZ3VyYXRvci5pbnRlZ3JhdGlvbnMucHJvdmlkZXJzLnZpYmVyIjowLCJjb25maWd1cmF0b3IuaW50ZWdyYXRpb25zLnByb3ZpZGVycy5mYWNlYm9vayI6MCwibWFuYWdlIjoyLCJjb25maWd1cmF0b3IucHJvcGVydGllcyI6MiwiY29uZmlndXJhdG9yIjoyLCJjb25maWd1cmF0b3IuZG93bmxvYWRhYmxlcyI6MiwiY29uZmlndXJhdG9yLnNlZ21lbnRzIjoyLCJjb25maWd1cmF0b3IuZXZlbnRzLmxlYWRlcmJvYXJkcyI6MiwiY29uZmlndXJhdG9yLnNjcmlwdHMubWVzc2FnZSI6MiwiY29uZmlndXJhdG9yLnNjcmlwdHMiOjIsImNvbmZpZ3VyYXRvci5zY3JpcHRzLmNhbGxiYWNrcyI6MiwiY29uZmlndXJhdG9yLnNjcmlwdHMucmVzcG9uc2UiOjJ9fSwicm9sZXMiOiIiLCJncm91cHMiOiJnc3JvbGUuZ2FtZUFkbWluIiwidXNlck5hbWUiOiJ1c2VyQGVtYWlsLmNvbSIsImV4cCI6MTQ4NzM0NTg0OCwidXNlcklkIjozMywiaXNzdWVyIjoibG9jYWxob3N0In0.c60Y9WBr6vV5JKf1yq3rlWsLe15G0QXkCgrevqRoRpI"
}

Get Scoped JWT Token

Request:

GET https://auth.gamesparks.net/restv2/auth/game/J3335lNuVXGb/jwt/nosql
X-GSAccessToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0ODczNDUxODQsImlkZW50aXR5IjoidXNlckBlbWFpbC5jb20ifQ.neJJnjlpXpYpCi7y6OK43oqELk6BNmKa1cC4JTZy4Z0
Content-Type: application/json

Response:

{
  "username": "user@email.com",
  "expiresAt": 1487345917287,
  "X-GS-JWT": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJnYW1lSWQiOjMzMzUsImNvdW50cnkiOiJVSyIsImFwaUtleSI6IkozMzM1bE51VlhHYiIsInBlcm1pc3Npb25zIjp7IkozMzM1bE51VlhHYiI6eyJub3NxbCI6Mn19LCJyb2xlcyI6IiIsImdyb3VwcyI6Imdzcm9sZS5nYW1lQWRtaW4iLCJ1c2VyTmFtZSI6InVzZXJAZW1haWwuY29tIiwiZXhwIjoxNDg3MzQ1OTE3LCJ1c2VySWQiOjMzLCJpc3N1ZXIiOiJsb2NhbGhvc3QifQ.SUXYd-q2Dt1LLX0f86JjfYje9ihBnQVXH_uCDMuzyp0"
}

Create an Event

Request:

POST https://config2.gamesparks.net/restv2/game/J3335lNuVXGb/config/~events
X-GSAccessToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0ODczNDUxODQsImlkZW50aXR5IjoidXNlckBlbWFpbC5jb20ifQ.neJJnjlpXpYpCi7y6OK43oqELk6BNmKa1cC4JTZy4Z0
Content-Type: application/json

{
  "description": "winRace",
  "name": "winRace",
  "shortCode": "winRace",
  "~attributes": [
    {
      "@id": "/~events/winRace/~attributes/SCORE",
      "dataType": "int",
      "defaultAggregationType": "MAX",
      "defaultValue": null,
      "name": "score",
      "shortCode": "SCORE"
    },
    {
      "@id": "/~events/winRace/~attributes/CAR",
      "dataType": "string",
      "defaultAggregationType": "SCRIPT",
      "defaultValue": null,
      "name": "car",
      "shortCode": "CAR"
    }
  ]
}

Response:

{
  "@id" : "/~events/winRace",
  "description" : "winRace",
  "name" : "winRace",
  "shortCode" : "winRace",
  "~attributes" : [ {
    "@id" : "/~events/winRace/~attributes/SCORE",
    "dataType" : "int",
    "defaultAggregationType" : "MAX",
    "defaultValue" : null,
    "name" : "score",
    "shortCode" : "SCORE"
  }, {
    "@id" : "/~events/winRace/~attributes/CAR",
    "dataType" : "string",
    "defaultAggregationType" : "SCRIPT",
    "defaultValue" : null,
    "name" : "car",
    "shortCode" : "CAR"
  } ]
}

Update the Description of an Event

Request:

PUT https://config2.gamesparks.net/restv2/game/J3335lNuVXGb/config/~events/winRace
X-GSAccessToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0ODczNDUxODQsImlkZW50aXR5IjoidXNlckBlbWFpbC5jb20ifQ.neJJnjlpXpYpCi7y6OK43oqELk6BNmKa1cC4JTZy4Z0
Content-Type: application/json

{
  "description": "Event called when you win a race"
}

Response:

{
  "@id": "/~events/winRace",
  "description": "Event called when you win a race",
  "name": "winRace",
  "shortCode": "winRace",
  "~attributes": [
    {
      "@id": "/~events/winRace/~attributes/SCORE",
      "dataType": "int",
      "defaultAggregationType": "MAX",
      "defaultValue": null,
      "name": "score",
      "shortCode": "SCORE"
    },
    {
      "@id": "/~events/winRace/~attributes/CAR",
      "dataType": "string",
      "defaultAggregationType": "SCRIPT",
      "defaultValue": null,
      "name": "car",
      "shortCode": "CAR"
    }
  ]
}

Add an Event Attribute

Request:

POST https://config2.gamesparks.net/restv2/game/J3335lNuVXGb/config/~events/winRace/~attributes
X-GSAccessToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0ODczNDUxODQsImlkZW50aXR5IjoidXNlckBlbWFpbC5jb20ifQ.neJJnjlpXpYpCi7y6OK43oqELk6BNmKa1cC4JTZy4Z0
Content-Type: application/json

{
  "dataType": "string",
  "defaultAggregationType": "SUPPLEMENTAL",
  "name": "track",
  "shortCode": "TRACK"
}

Response:

{
  "@id": "/~events/winRace/~attributes/TRACK",
  "dataType": "string",
  "defaultAggregationType": "SUPPLEMENTAL",
  "defaultValue": null,
  "name": "track",
  "shortCode": "TRACK"
}

Delete an Event Attribute

Request:

DELETE https://config2.gamesparks.net/restv2/game/J3335lNuVXGb/config/~events/winRace/~attributes/TRACK
X-GSAccessToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0ODczNDUxODQsImlkZW50aXR5IjoidXNlckBlbWFpbC5jb20ifQ.neJJnjlpXpYpCi7y6OK43oqELk6BNmKa1cC4JTZy4Z0
Content-Type: application/json

Response:


{
  "message": "SUCCESS"
}