Making Requests

Content Negotiation

Clients using the API should specify that they accept responses using the application/vnd.api+json format. For convenience, we will also accept application/json since it is the default for many popular client libraries.

The Server will respond with a Content-Type header that mirrors the format requested by the client.

Regions

The Vainglory Game Data Service currently supports the following regions:

General Region Shards: To find data regarding live servers, where all data is found, please use the following shards:

  • China cn
  • North America: na
  • Europe: eu
  • South America: sa
  • East Asia: ea
  • Southeast Asia (SEA): sg

Tournament Region Shards: To find data regarding professional eSports, which take place on the private client only, please use the following shards:

  • North America Tournaments: tournament-na
  • Europe Tournaments: tournament-eu
  • East Asia Tournaments: tournament-ea
  • Southeast Asia Tournaments: tournament-sg

Please note: Choosing a specific region is currently required

To specify a region, use this code:

"...gamelockerapp.com/shards/<region>/..."

GZIP

Clients can specify the header Accept-Encoding: gzip, and the server will compress responses. Responses will be returned with Content-Encoding: gzip.

Given the size of matches, this can have significant performance benefits.

To specify the header Accept-Encoding, use this code:

Shell:

-H "Accept-Encoding: gzip"

Java:

conn.setRequestProperty("Accept-Encoding","gzip");

Python:

header = {"Accept-Encoding":"gzip"}

Go:

req.Header.Set("Accept-Encoding", "gzip")

Search Time

Defaults:

  • Data retention period is 120 days.
  • The max search time span between createdAt-start and createdAt-end is 28 days.
  • If you don’t specify createdAt-start, the default is now() - 28 days.
  • If you don’t specify createdAt-end, the default is now().
  • If you search for a time > now, the default is now().
  • If you search for a time before the retention period, the default is the retention period (now() - 120 days).
  • If createdAt-start >= createdAt-end, you will receive an error.

Sorting

The default sort order is always ascending. Ascending corresponds to the standard order of numbers and letters, i.e. A to Z, 0 to 9). For dates and times, ascending means that earlier values precede later ones e.g. 1/1/2000 will sort ahead of 1/1/2001.

All resource collections have a default sort order. In addition, some resources provide the ability to sort according to one or more criteria (“sort fields”).

If sort fields are prefixed with a minus, the order will be changed to descending.

The example below will return the oldest articles first:

".../matches?sort=createdAt"

The example below will return the newest articles first:

".../matches?sort=-createdAt"

Cross Origin Resource Sharing

This is what the CORS preflight request looks like. The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. You can read the CORS W3C Recommendation here.

Here’s a sample request sent from a browser hitting http://example.com:

Shell:

curl -i https://api.dc01.gamelockerapp.com/status -H "Origin: http://example.com"
HTTP/1.1 200 OK
...
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Content-Length

This is what the CORS preflight request looks like:

curl -i https://api.dc01.gamelockerapp.com/status -H "Origin: http://example.com" -X OPTIONS
HTTP/1.1 200 OK
...
Access-Control-Allow-Headers: Origin,X-Title-Id,Authorization
Access-Control-Allow-Methods: GET,POST,OPTIONS
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 86400