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}