docbook.xml

<?xml version="1.0" encoding="UTF-8"?>
<book version="5.0" xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:svg="http://www.w3.org/2000/svg"
      xmlns:m="http://www.w3.org/1998/Math/MathML"
      xmlns:html="http://www.w3.org/1999/xhtml"
      xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>Blizzard Community Platform API Documentation</title>

    <author>
      <orgname>Blizzard Entertainment</orgname>

      <email>api-support@blizzard.com</email>
    </author>

    <pubdate>7/5/2011</pubdate>

    <abstract>
      <para>This is the documentation for the RESTful APIs exposed through the
      World of Warcraft community site as a service to the World of Warcraft
      community.</para>
    </abstract>
  </info>

  <preface>
    <title>Introduction</title>

    <para>The Blizzard Community Platform API provides a number of resources
    for developers and Wow enthusiasts to gather data about their characters,
    guilds and arena teams. This documentation is primarily for developers and
    third parties.</para>

    <para>Blizzard's epic gaming experiences often take place in game, but can
    lead to rewarding and lasting experiences out of game as well. Through
    exposing key sets of data, we can enable the community to create extended
    communities to continue that epic experience.</para>
  </preface>

  <chapter>
    <title>Features</title>

    <para>Before getting started with the Community Platform API, programmers
    must first understand how the API is organized and how it works. The
    following sections provide a high level overview of the features of this
    API. It is recommended that the reader have knowledge of the HTTP protocol
    as well as a general understanding of web technologies.</para>

    <section>
      <title>REST</title>

      <para>The API is <emphasis>mostly</emphasis> RESTful. Data is exposed in
      the form of URIs that represent resources and can be fetched with HTTP
      clients (like web browsers). At this time, the API is limited to
      read-only operations.</para>

      <para>The character and guild API resources do honor HTTP requests that
      contain the "Last-Modified" header.</para>
    </section>

    <section>
      <title>Access and Regions</title>

      <para>To access the API, HTTP requests can be made to specific URLs and
      resources exposed on the regional Battle.net domains.</para>

      <example>
        <title>An example API request and response.</title>

        <programlisting>GET /api/wow/realm/status HTTP/1.1
Host: us.battle.net
&lt;http headers&gt;</programlisting>

        <programlisting>HTTP/1.1 200 OK
&lt;http headers&gt;

{"realms":[ ... ]}</programlisting>
      </example>

      <para>The regions where this API is available are:<itemizedlist>
          <listitem>
            <para>us.battle.net</para>
          </listitem>

          <listitem>
            <para>eu.battle.net</para>
          </listitem>

          <listitem>
            <para>kr.battle.net</para>
          </listitem>

          <listitem>
            <para>tw.battle.net</para>
          </listitem>
        </itemizedlist></para>

      <para>The data available through the API is limited to the region that
      it is in. Hence, US APIs accessed through us.battle.net will only
      contain data within US battlegroups and realms. Support for locales is
      limited to those supported on the World of Warcraft community
      sites.</para>
    </section>

    <section>
      <title>Throttling</title>

      <para>Consumers of the API can make a limited number of requests per
      day, as stated in the API Policy and Terms of Use. For anonymous
      consumers of the API, the number of requests that can be made per day is
      set to 3,000. Once that threshold is reached, depending on site activity
      and performance, subsequent requests may be denied. High limits are
      available to registered applications.</para>
    </section>

    <section>
      <title>Authentication</title>

      <para>Although most of the application can be accessed without any form
      of authentication, we do support a form application registration and
      authentication. Application authentication involves creating and
      including an application identifier and a request signature and
      including those values with the request headers.</para>

      <para>The primary benefit to making requests as an authenticated
      application is that you can make more requests per day.</para>

      <section>
        <title>Application Registration</title>

        <para>To send authenticated request you first need to register an
        application. Because registration isn't automated, application
        registration is limited to those who meet the following
        criteria:</para>

        <itemizedlist>
          <listitem>
            <para>You plan on making requests from one or more IP addresses.
            (e.g. a production environment and development environment)</para>
          </listitem>

          <listitem>
            <para>You can justify making more than 2,000 requests per day from
            one or more IP addresses.</para>
          </listitem>
        </itemizedlist>

        <para>Registering an application is a matter of providing a
        description of the application, how you plan on using the API and your
        contact information to <email>api-support@blizzard.com</email> with
        the subject "Application Registration Request". Once we receive your
        request, we will contact you to either provide additional information
        or with application keys to use.</para>
      </section>

      <section>
        <title>Authentication Process</title>

        <para>To authenticate a request, simple include the "Authorization"
        header with your application identifier and the request
        signature.</para>

        <example>
          <title>An example authenticated request</title>

          <programlisting>GET /api/wow/character/Medivh/Thrall HTTP/1.1
Host: us.battle.net
Date: Fri, 10 Jun 2011 20:59:24 GMT
Authorization: <computeroutput>BNET</computeroutput> <computeroutput>c1fbf21b79c03191d</computeroutput>:<computeroutput>+3fE0RaKc+PqxN0gi8va5GQC35A=</computeroutput></programlisting>
        </example>

        <para>In the above exmple, the value of the Authorization header has
        three parts "<code>BNET</code>", "<code>c1fbf21b79c03191d</code>" and
        "<code>+3fE0RaKc+PqxN0gi8va5GQC35A=</code>". The first part is a
        processing directive for the Authorization header. The second and
        third values are the application public key and the request signature.
        The application public key is assigned by Blizzard during the
        application registration process. The signature is generated with each
        request and is discribed by the following algorithm.</para>

        <programlisting>UrlPath = &lt;HTTP-Request-URI, from the port to the query string&gt;

StringToSign = HTTP-Verb + "\n" +
    Date + "\n" +
    UrlPath + "\n";

Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( PrivateKey, StringToSign ) ) );

Authorization = "BNET" + " " + PublicKey + ":" + Signature;</programlisting>

        <para>The above process can be seen in action by filling in the
        blanks:</para>

        <programlisting>UrlPath = "/api/wow/realm/status"

StringToSign = "GET" + "\n" +
    "Fri, 10 Jun 2011 21:37:34 GMT" + "\n" +
    UrlPath + "\n";

Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( "examplesecret" ), StringToSign ) );

Authorization = "BNET" + " " + "examplekey" + ":" + Signature;</programlisting>

        <para>The date timestamp used in the above algorithm and example is
        the value of the Date HTTP header. The two date values, the first
        being used to sign the request and the second as sent with the request
        headers, must be the same and within 15 seconds of the current GMT
        time.</para>
      </section>
    </section>

    <section>
      <title>Formats and Protocols</title>

      <para>Data returned in the response message is provided in JSON format.
      Please refer to the examples provided with each API section for
      additional information.</para>
    </section>

    <section>
      <title>Error Handling</title>

      <para>Although several of the API resources have specific error
      responses that corrospond to specific situations, there are several
      generic error responses that you should be aware of.</para>

      <para>Errors are returned as JSON objects that contain
      "<code>status</code>" and "<code>reason</code>" attributes. The value of
      the "<code>status</code>" attribute will always be "nok". The reason
      will be an english string that may be, but is not limited to, one of the
      following strings.</para>

      <variablelist>
        <varlistentry>
          <term>Invalid Application</term>

          <listitem>
            <para>HTTP Response Code: 500</para>

            <para>A request was made including application identification
            information, but either the application key is invalid or
            missing.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Invalid application permissions.</term>

          <listitem>
            <para>HTTP Response Code: 500</para>

            <para>A request was made to an API resource that requires a higher
            application permission level.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Access denied, please contact api-support@blizzard.com</term>

          <listitem>
            <para>HTTP Response Code: 500</para>

            <para>The application or IP address has been blocked from making
            further requests. This ban may not be permanent.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>When in doubt, blow it up. (page not found)</term>

          <listitem>
            <para>HTTP Response Code: 404</para>

            <para>A request was made to a resource that doesn't exist.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>If at first you don't succeed, blow it up again. (too many
          requests)</term>

          <listitem>
            <para>HTTP Response Code: 500</para>

            <para>The application or IP has been throttled.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Have you not been through enough? Will you continue to fight
          what you cannot defeat? (something unexpected happened)</term>

          <listitem>
            <para>HTTP Response Code: 500</para>

            <para>There was a server error or equally catastrophic exception
            preventing the request from being fulfilled.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Invalid authentication header.</term>

          <listitem>
            <para>HTTP Response Code: 500</para>

            <para>The application authorization information was mallformed or
            missing when expected.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Invalid application signature.</term>

          <listitem>
            <para>HTTP Response Code: 500</para>

            <para>The application request signature was missing or invalid.
            This will also be thrown if the request date outside of a 15
            second window from the current GMT time.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <example>
        <title>An example API request and and error response</title>

        <programlisting>GET /api/wow/data/boss/45 HTTP/1.1
Host: us.battle.net
&lt;http headers&gt;</programlisting>

        <programlisting>HTTP/1.1 404 Not Found
&lt;http headers&gt;

{"status":"nok", "reason": "When in doubt, blow it up. (page not found)"}</programlisting>
      </example>
    </section>

    <section>
      <title>Support</title>

      <para>For questions about the API, please use the Community Platform API
      forums as a platform to ask questions and get help.</para>

      <address><link xlink:href="http://us.battle.net/wow/en/forum/2626217/">http://us.battle.net/wow/en/forum/2626217/</link></address>

      <para>You can also email <email>api-support@blizzard.com</email> for
      matters that you may not want public discussion for.</para>
    </section>
  </chapter>

  <chapter>
    <title>API Reference</title>

    <section>
      <title>Character Resources</title>

      <para>Character APIs currently provide character profile
      information.</para>

      <section>
        <title>Profile</title>

        <para>The Character Profile API is the primary way to access character
        information. This Character Profile API can be used to fetch a single
        character at a time through an HTTP GET request to a URL describing
        the character profile resource. By default, a basic dataset will be
        returned and with each request and zero or more additional fields can
        be retrieved. To access this API, craft a resource URL pointing to the
        character whos information is to be retrieved.</para>

        <programlisting>URL = Host + "/api/wow/character/" + Realm + "/" + CharacterName

Realm = &lt;proper realm name&gt; | &lt;normalized realm name&gt;</programlisting>

        <para>There are no required query string parameters when accessing
        this resource, although the "<code>fields</code>" query string
        parameter can optionally be passed to indicate that one or more of the
        optional datasets is to be retrieved. Those additional fields are
        listed in the subsection titled "Optional Fields".</para>

        <example>
          <title>An example Character Profile API request and
          response.</title>

          <programlisting>GET /api/wow/character/Medivh/Uther?fields=guild
Host: us.battle.net</programlisting>

          <programlisting>HTTP/1.1 200 OK
&lt;http headers&gt;

{"realm": "Medivh", "name": "Uther", "level": 85, "lastModified": 1307596000000, "thumbnail": "medivh/1/1-avatar.jpg",
"race": 1, "achievementPoints": 9745, "gender": 0, "class": 2, "guild": { ... } }</programlisting>
        </example>

        <para>The core dataset returned includes the character's realm, name,
        level, last modified timestamp, thumbnail, race id, achievement points
        value, gender id and class id.</para>

        <section>
          <title>Optional Fields</title>

          <para>This section contains a list of the optional fields that can
          be requested through the mentioned "<code>fields</code>" query
          string parameter.</para>

          <variablelist>
            <varlistentry>
              <term>guild</term>

              <listitem>
                <para>A summary of the guild that the character belongs to. If
                the character does not belong to a guild and this field is
                requested, this field will not be exposed.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>stats</term>

              <listitem>
                <para>A map of character attributes and stats.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>talents</term>

              <listitem>
                <para>A list of talent structures.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>items</term>

              <listitem>
                <para>A list of items equipted by the character. Use of this
                field will also include the <emphasis>average item
                level</emphasis> and <emphasis>average item level
                equipped</emphasis> for the character.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>reputation</term>

              <listitem>
                <para>A list of the factions that the character has an
                associated reputation with.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>titles</term>

              <listitem>
                <para>A list of the titles obtained by the character.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>professions</term>

              <listitem>
                <para>A list of the character's professions. It is important
                to note that when this information is retrieved, it will also
                include the known recipes of each of the listed
                professions.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>appearance</term>

              <listitem>
                <para>A map of values that describes the face, features and
                helm/cloak display preferences and attributes.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>companions</term>

              <listitem>
                <para>A list of all of the non-combat pets obtained by the
                character.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>mounts</term>

              <listitem>
                <para>A list of all of the mounts obtained by the
                character.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>pets</term>

              <listitem>
                <para>A list of all of the combat pets obtained by the
                character.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>achievements</term>

              <listitem>
                <para>A map of achievement data including completion
                timestamps and criteria information.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>progression</term>

              <listitem>
                <para>A list of raids and bosses indicating raid progression
                and completedness.</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <example>
            <title>An example Character Profile request with several addtional
            fields.</title>

            <programlisting>GET /api/wow/character/Medivh/Uther?fields=guild,items,professions,reputation,stats
Host: us.battle.net</programlisting>
          </example>

          <section>
            <title>guild</title>

            <para>When a guild is requested, a map is returned with key/value
            pairs that describe a basic set of guild information. Note that
            the rank of the character is not included in this block as it
            describes a guild and not a membership of the guild. To retreive
            the character's rank within the guild, you must specific a
            seperate request to the guild profile resource.</para>

            <example>
              <title>An example guild on Medivh</title>

              <programlisting language="json">{
  "guild":{
    "name":"Roll the Dice",
    "realm":"Medivh",
    "level":25,
    "members":177,
    "achievementPoints":790,
    "emblem":{
      "icon":119,
      "iconColor":"ffffffb1",
      "border":-1,
      "borderColor":"ffffffff",
      "backgroundColor":"ffffff91"
    }
  }
}</programlisting>
            </example>
          </section>

          <section>
            <title>items</title>

            <para>When the items field is used, a map structure is returned
            that contains information on the equipped items of that character
            as well as the average item level of the character.</para>

            <example>
              <title>An example items field</title>

              <programlisting language="json"><xi:include
                  href="character-items.json" parse="text" /></programlisting>
            </example>
          </section>

          <section>
            <title>stats</title>

            <example>
              <title>An example stats field</title>

              <programlisting language="json"><xi:include
                  href="character-stats.json" parse="text" /></programlisting>
            </example>
          </section>

          <section>
            <title>talents</title>

            <example>
              <title>An example talents field</title>

              <programlisting language="json"><xi:include
                  href="character-talents.json" parse="text" /></programlisting>
            </example>
          </section>

          <section>
            <title>reputation</title>

            <example>
              <title>An example reputation field</title>

              <programlisting language="json"><xi:include
                  href="character-reputation.json" parse="text" /></programlisting>
            </example>
          </section>

          <section>
            <title>titles</title>

            <example>
              <title>An example titles field</title>

              <programlisting language="json"><xi:include
                  href="character-titles.json" parse="text" /></programlisting>
            </example>
          </section>

          <section>
            <title>professions</title>

            <example>
              <title>An example professions field</title>

              <programlisting language="json"><xi:include
                  href="character-professions.json" parse="text" /></programlisting>
            </example>
          </section>

          <section>
            <title>appearance</title>

            <example>
              <title>An example appearance field</title>

              <programlisting language="json">{
  "appearance":{
    "faceVariation":2,
    "skinColor":0,
    "hairVariation":1,
    "hairColor":8,
    "featureVariation":2,
    "showHelm":true,
    "showCloak":true
  }
}</programlisting>
            </example>
          </section>

          <section>
            <title>companions</title>

            <example>
              <title>An example companions field</title>

              <programlisting language="json">{
  "companions":[
    4055,
    10673,
    10674,
    10676,
    10677
  ]
}</programlisting>
            </example>
          </section>

          <section>
            <title>mounts</title>

            <example>
              <title>An example mounts field</title>

              <programlisting language="json">{
  "mounts":[
    30174
  ]
}</programlisting>
            </example>
          </section>

          <section>
            <title>pets</title>

            <example>
              <title>An example pets field</title>

              <programlisting language="json">{
  "pets":[
    {
      "name":"Wolf",
      "creature":17280,
      "selected":true,
      "slot":0
    },
    {
      "name":"Bear",
      "creature":29319,
      "slot":8
    },
    {
      "name":"Kat",
      "creature":28404,
      "slot":7
    },
    {
      "name":"Cat",
      "creature":2071,
      "slot":6
    }
  ]
}</programlisting>
            </example>
          </section>

          <section>
            <title>achievements</title>

            <example>
              <title>An example achievements field</title>

              <programlisting><xi:include href="character-achievements.json"
                  parse="text" /></programlisting>
            </example>
          </section>

          <section>
            <title>progression</title>

            <example>
              <title>An example progression field</title>

              <programlisting><xi:include href="character-progression.json"
                  parse="text" /></programlisting>
            </example>
          </section>
        </section>
      </section>
    </section>

    <section>
      <title>Guild Resources</title>

      <para>Guild APIs currently provide guild profile information.</para>

      <section>
        <title>Profile API</title>

        <para>The guild profile API is the primary way to access guild
        information. This guild profile API can be used to fetch a single
        guild at a time through an HTTP GET request to a url describing the
        guild profile resource. By default, a basic dataset will be returned
        and with each request and zero or more additional fields can be
        retrieved. To access this API, craft a resource URL pointing to the
        guild whos information is to be retrieved.</para>

        <programlisting>URL = Host + "/api/wow/guild/" + Realm + "/" + GuildName

Realm = &lt;proper realm name&gt; | &lt;normalized realm name&gt;</programlisting>

        <para>There are no required query string parameters when accessing
        this resource, although the "<code>fields</code>" query string
        parameter can optionally be passed to indicate that one or more of the
        optional datasets is to be retrieved. Those additional fields are
        listed in the subsection titled "Optional Fields".</para>

        <example>
          <title>An example Guild Profile request and response.</title>

          <programlisting>GET /api/wow/guild/Medivh/Roll%20the%20Dice
Host: us.battle.net</programlisting>

          <programlisting>HTTP/1.1 200 OK
&lt;http headers&gt;

{ "name":"Roll the Dice", "level":25, "side":"alliance", "achievementPoints":800 }</programlisting>
        </example>

        <para>The core dataset returned includes the guild's name, level,
        faction and achievement points.</para>

        <section>
          <title>Optional Fields</title>

          <para>This section contains a list of the optional fields that can
          be requested.</para>

          <variablelist>
            <varlistentry>
              <term>members</term>

              <listitem>
                <para>A list of characters that are a member of the
                guild</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>achievements</term>

              <listitem>
                <para>A set of data structures that describe the achievements
                earned by the guild.</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <example>
            <title>An example Guild Profile request with several addtional
            fields.</title>

            <programlisting>GET /api/wow/guild/Medivh/Roll%20the%20Dice?fields=achievements,members
Host: us.battle.net</programlisting>
          </example>

          <section>
            <title>members</title>

            <para>When the members list is requrested, a list of character
            objects is returned. Each object in the returned members list
            contains a character block as well as a rank field.</para>

            <example>
              <title>An example members block</title>

              <programlisting language="json"><xi:include
                  href="guild-members.json" parse="text" /></programlisting>
            </example>
          </section>

          <section>
            <title>achievements</title>

            <para>When requesting achievement data, several sets of data will
            be returned.</para>

            <variablelist>
              <varlistentry>
                <term>achievementsCompleted</term>

                <listitem>
                  <para>A list of achievement ids.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>achievementsCompletedTimestamp</term>

                <listitem>
                  <para>A list of timestamps whose places corrospond to the
                  achievement ids in the "achievementsCompleted" list. The
                  value of each timestamp indicates when the related
                  achievement was earned by the guild.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>criteria</term>

                <listitem>
                  <para>A list of criteria ids that can be used to determine
                  the partial completedness of guild achievements.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>criteriaQuantity</term>

                <listitem>
                  <para>A list of values associated with a given achievement
                  criteria. The position of a value corrosponds to the
                  position of a given achivement criteria.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>criteriaTimestamp</term>

                <listitem>
                  <para>A list of timestamps where the value represents when
                  the criteria was considered complete. The position of a
                  value corrosponds to the position of a given achivement
                  criteria.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>criteriaCreated</term>

                <listitem>
                  <para>A list of timestamps where the value represents when
                  the criteria was considered started. The position of a value
                  corrosponds to the position of a given achivement
                  criteria.</para>
                </listitem>
              </varlistentry>
            </variablelist>

            <example>
              <title>An example achievements block</title>

              <programlisting><xi:include href="guild-achievements.json"
                  parse="text" /></programlisting>
            </example>
          </section>
        </section>
      </section>
    </section>

    <section>
      <title>Realm Resources</title>

      <para>Realm APIs currently provide realm status information.</para>

      <section>
        <title>Realm Status</title>

        <para>The realm status API allows developers to retrieve realm status
        information. This information is limited to whether or not the realm
        is up, the type and state of the realm and the current
        population.</para>

        <programlisting>URL = Host + "/api/wow/realm/status"</programlisting>

        <para>There are no required query string parameters when accessing
        this resource, although the "<code>realms</code>" query string
        parameter can optionally be passed to limit the realms returned to one
        or more.</para>

        <example>
          <title>An example Realm Status request and response</title>

          <programlisting>GET /api/wow/realm/status?realms=Medivh,Lightbringer HTTP/1.1
Host: us.battle.net
&lt;http headers&gt;</programlisting>

          <programlisting>HTTP/1.1 200 OK
&lt;http headers&gt;

{
  "realms":[
    {
      "type":"pve",
      "queue":false,
      "status":true,
      "population":"high",
      "name":"Lightbringer",
      "slug":"lightbringer"
    },
    {
      "type":"pve",
      "queue":false,
      "status":true,
      "population":"medium",
      "name":"Medivh",
      "slug":"medivh"
    }
  ]
}</programlisting>
        </example>
      </section>
    </section>

    <section>
      <title>Data Resources</title>

      <para>The data APIs provide information that can compliment profile
      information to provide structure, definition and context.</para>

      <section>
        <title>Character Races</title>

        <para>The character races data API provides a list of character
        races.</para>

        <programlisting>URL = Host + "/api/wow/data/character/races"</programlisting>
      </section>

      <section>
        <title>Character Classes</title>

        <para>The character classes data API provides a list of character
        classes.</para>

        <programlisting>URL = Host + "/api/wow/data/character/classes"</programlisting>
      </section>

      <section>
        <title>Guild Rewards</title>

        <para>The guild rewards data API provides a list of all guild
        rewards.</para>

        <programlisting>URL = Host + "/api/wow/data/guild/rewards"</programlisting>
      </section>

      <section>
        <title>Guild Perks</title>

        <para>The guild perks data API provides a list of all guild
        perks.</para>

        <programlisting>URL = Host + "/api/wow/data/guild/perks"</programlisting>
      </section>

      <section>
        <title>Items</title>

        <para>The items data API provides detailed item information.</para>

        <programlisting>URL = Host + "/api/wow/data/item/" + ItemId</programlisting>

        <example>
          <title>An example Item Data API request and response</title>

          <programlisting>GET /api/wow/data/item/38268 HTTP/1.1
Host: us.battle.net
&lt;http headers&gt;</programlisting>

          <programlisting>HTTP/1.1 200 OK
&lt;http headers&gt;

{
  "id":38268,
  "disenchantingSkillRank":-1,
  "description":"Give to a Friend",
  "name":"Spare Hand",
  "stackable":1,
  "itemBind":{
    "id":0
  },
  "bonusStats":[],
  "itemSpells":[],
  "buyPrice":12,
  "itemClass":{
    "class":2,
    "name":"Weapon"
  },
  "itemSubClass":{
    "subclassId":14,
    "name":"Miscellaneous"
  },
  "containerSlots":0,
  "weaponInfo":{
    "damage":[
      {
        "minDamage":1,
        "maxDamage":2
      }
    ],
    "weaponSpeed":2.5,
    "dps":0.6
  },
  "inventoryType":13,
  "equippable":true,
  "itemLevel":1,
  "maxCount":0,
  "maxDurability":16,
  "minFactionId":0,
  "minReputation":0,
  "quality":0,
  "sellPrice":2,
  "requiredLevel":70,
  "requiredSkill":0,
  "requiredSkillRank":0,
  "itemSource":{
    "sourceId":0,
    "sourceType":"NONE"
  },
  "baseArmor":0,
  "hasSockets":false,
  "isAuctionable":true
}</programlisting>
        </example>
      </section>
    </section>
  </chapter>

  <chapter>
    <title>API Policy</title>

    <para>The final policy document is being reviewed and will be published at
    a later date.</para>
  </chapter>

  <chapter>
    <title>Frequently Asked Questions</title>

    <qandaset>
      <qandadiv>
        <qandaentry>
          <question>
            <para>Is there an official library or reference implementation
            provided with these web APIs?</para>
          </question>

          <answer>
            <para>No, Blizzard Entertainment has not released an officially
            support client library to consume the web APIs. There are a number
            of unofficial libraries that follow the spec provided by this
            documentation. You are not limited to or forced to use one of the
            libraries below and can create your own.</para>

            <variablelist>
              <varlistentry>
                <term>Python</term>

                <listitem>
                  <para>https://github.com/vishnevskiy/battlenet</para>
                </listitem>
              </varlistentry>
            </variablelist>
          </answer>
        </qandaentry>

        <qandaentry>
          <question>
            <para>What about XML/Atom/JSONP/Other data forms?</para>
          </question>

          <answer>
            <para>We decided to roll out JSON for numerous reasons. One of the
            main reasons is that it allows developers and website operators to
            easily embed requests that consume this date into their
            websites.</para>
          </answer>
        </qandaentry>
      </qandadiv>
    </qandaset>
  </chapter>
</book>