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

Requests to the Battlerite Game Data Service are done using the “global” region shard.

"...battlerite.com/shards/global/..."

The actual server regions will be included in the stats object as part of a match.

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

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 ‘example.com’:

Shell:

curl -i https://api.developer.battlerite.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.developer.battlerite.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