Game Data APIs

This page provides a brief overview of the Game Data and Profile APIs which were originally announced on the dev.battle.net developer forums.

Introduction

The Game Data and Profile APIs are part of a larger strategy that makes it easier for Blizzard to share data internally and externally. This allows Blizzard teams to use a single, well-defined interface to publish data in an easily consumable format that has an agreed upon schema between publisher and consumer.

What is the difference between the Game Data API and Profile API?

The difference between Game Data and Profile APIs is the type of data they handle. As you might have guessed from the names, the Profile API is used to store data related to individuals, their characters, or accounts (which we call profile data), while the Game Data API stores all other reference data related to a game itself (which we call static data) and constantly changing world related data that may have references to profile documents, but is not wholly owned by the players (which we call dynamic data).

Game Data includes generic information like a list of abilities available to a character, server status, or even the current leaderboards for a game. On the other hand, Profile data includes the equipment on a character, an account's achievements, or a list of characters. As a rule of thumb, Profile data is more sensitive than Game Data. In order to access restricted data, you need to request and receive approval for additional OAuth scopes.

How are Game Data/Profile APIs different from the Community APIs?

The major differences between the existing Community APIs and the Game Data APIs are URL structures, response structures, the introduction of namespaces, and the authorization strategy.

How do response structures differ from the existing Community APIs?

Unlike the existing Community APIs which perform business computations on a data set to formulate a response, the Game Data APIs return JSON documents directly to the consumer in the exact format and structure they are stored. The only time when a document is returned in a different format than that which it is stored is when the consumer makes a request that includes a localization identifier.

You keep mentioning documents, what is a "document"?

Documents (or document based stores) is a concept where data is stored in a semi-structured way which does not follow many of the common relational database concepts. A key component of a document is that the data returned to a consumer in response to a request represents the document's data in its entirety at the time at which it was published. Document-based stores and APIs have become more popular over the last few years with the introduction and growing popularity of NoSQL databases.

How does the concept of documents affect me as a consumer?

Increased number of requests:

When consuming the documents exposed through the Game Data APIs, a consumer may be required to make an increased number of requests in order to resolve fully all of the related data for a requested resource. As mentioned above in the "...what is a 'document'?" section, the responses from the Game Data APIs represent a single resource fully, rather than a composite object that represents several other objects. This means that for some data, the consumer may need to make several requests to related resources by following links in the originally requested resources before they are able to obtain all of the desired data.

While the overall number of requests needed to fully resolve a resource can be expected to increase, some of the APIs which makeup the collective Game Data APIs and Profile APIs may include basic or commonly accessed data such as localized strings, character names, or realm slugs in parent documents in order to reduce excessive requests to child documents, though this may differ depending on which API is being consumed.

Increased discoverability:

Where traditional APIs would often represent a relationship between two resources by returning a foreign key or ID that references the primary key in a related table, or a string name such as the "realm" property in the below example, the Game Data APIs aim to represent a relationship using the concept of a "link" which contains a "href" property that includes the URL to the exact location of the related document.

Community API Pattern:

{
  ...
  "name": "Maguthul",
  "realm": "Test Realm",
  ...
}

Game Data / Profile API Pattern:

{
    ...
    "name": "Maguthul",
    "realm": {
        "key": {
            "href": "http://us.api.battle.net/data/wow/realm/12345"
        },
        "name": "Test Realm"
    }
    ...
}

What is a namespace?

With the Game Data / Profile APIs we are now introducing the concept of a "namespace". Similar to how namespaces work in programming languages to group and separate resources or classes, namespaces allow publishing of multiple documents to a single url without overwriting an existing document. This allows all versions of that document to remain accessible within a specific context.

Although this allows multiple instances of the same type of document to coexist, namespaces should not be considered strict or semantic versioning, though the namespace will sometimes contain a version identifier.

How do you specify a namespace?

There are currently two methods for specifying a namespace when making a request to the Game Data / Profile APIs, a ?namespace= query parameter, or a Battlenet-Namespace request header.

Type Name
Query Parameter ?namespace=
Request Header Battlenet-Namespace

What data is namespaced?

All data published to the Game Data / Profile APIs are published to namespaces, however, the naming strategies and when they change are determined by the specific publisher of the API. For information on a specific game's namespacing strategy, refer to the documentation for that game and API under the Game Data APIs header on the right-side navigation.

How has the authorization strategy changed?

Previously with the Community APIs, a consuming application or client would provide a client_id query parameter with every request. With the Game Data / Profile APIs, consumers will now be required to provide an access_token query parameter, or an Authorization: Bearer <token> header when making a request for a resource.

To obtain an access_token follow the Client Credentials Flow, which is outlined in Using OAuth.

Localization

In the past, localization has been handled by providing a locale query parameter in the request url which would inform the API which is the preferred language for text to be returned (which would default to "en_US" when omitted). Though the locale query parameter is still supported, the Game Data and Profile APIs handle localized responses differently. Response objects will now default to including all locales for a localized string, filtering down to a specific locale if one is specified in the request.

Default response:

{
  ...
  "faction": {
      "id": 1,
      "type": "HORDE",
      "name": {
          "en_US": "Horde",
          "es_MX": "Horda",
          "pt_BR": "Horda",
          "de_DE": "Horde",
          "es_ES": "Horda",
          "fr_FR": "Horde",
          "it_IT": "Orda",
          "pt_PT": "Horda",
          "ru_RU": "Орда",
          "ko_KR": "호드",
          "zh_TW": "部落",
          "zh_CN": "部落"
      }
  }
  ...
}

Locale specific response (en_US):

{
  ...
  "faction": {
      "id": 1,
      "type": "HORDE",
      "name": "Horde"
  }
  ...
}

As this will impact the structure of the response and localization strategies may differ between APIs, it is recommended that users review the API documentation to understand localization impacts before consuming the data.

Further Learning & Discussion

Head on over to the dev.battle.net API Discussion forums for questions or to provide feedback.