Class: Battlenet

Inherits:
Object
  • Object
show all
Includes:
Modules::Achievement, Modules::Arena, Modules::Auction, Modules::Character, Modules::Data, Modules::Guild, Modules::Item, Modules::Pvp, Modules::Quest, Modules::Realm, Modules::Recipe, HTTParty
Defined in:
lib/battlenet/battlenet.rb,
lib/battlenet/version.rb,
lib/battlenet/modules/pvp.rb,
lib/battlenet/modules/data.rb,
lib/battlenet/modules/item.rb,
lib/battlenet/modules/arena.rb,
lib/battlenet/modules/guild.rb,
lib/battlenet/modules/quest.rb,
lib/battlenet/modules/realm.rb,
lib/battlenet/authentication.rb,
lib/battlenet/modules/recipe.rb,
lib/battlenet/modules/auction.rb,
lib/battlenet/modules/character.rb,
lib/battlenet/modules/achievement.rb,
lib/battlenet/exceptions/api_exception.rb

Overview

Battlenet exposes the Blizzard Battle.net Community Platform API via an easy-to-use interface.

The main API class includes several Modules that define methods for collecting specific API data. See the documentation for Battlenet::Modules for a list of these modules.

Specific details about the information returned from the API can be found at Blizzard's official Community Platform API documentation.

Examples:

Return basic information about a character named Cyaga from the US realm Nazjatar


api  = Battlenet.new :us
char = api.character 'Nazjatar', 'Cyaga'
char['level']
# => 85

Return additional information about a character


api  = Battlenet.new :us
char = api.character 'Nazjatar', 'Cyaga', :fields => 'titles'
selected_title = char['titles'].find { |t| t['selected'] == true }
selected_title['name']
# => "%s, Guardian of Cenarius"

See Also:

Author:

Defined Under Namespace

Modules: Modules Classes: ApiException, Authentication

Constant Summary collapse

VERSION = 
"1.4.0"

Class Attribute Summary collapse

Instance Method Summary collapse

Methods included from Modules::Data

#battlegroups, #character_achievements, #character_classes, #character_races, #guild_achievements, #guild_perks, #guild_rewards, #item_classes

Methods included from Modules::Pvp

#arena_ladder, #rated_bg_ladder

Methods included from Modules::Arena

#arena

Methods included from Modules::Quest

#quest

Methods included from Modules::Recipe

#recipe

Methods included from Modules::Achievement

#achievement

Methods included from Modules::Item

#item, #item_set

Methods included from Modules::Auction

#auction, #auction_data

Methods included from Modules::Realm

#realm

Methods included from Modules::Guild

#guild

Methods included from Modules::Character

#character

Constructor Details

#initialize(region = :us, public = nil, private = nil) ⇒ Battlenet

Creates a new instance of the Battlenet API.

Parameters:

  • region (Symbol) (defaults to: :us) —

    the region to perform API calls against.

  • public (String|nil) (defaults to: nil) —

    the public key to use when signing requests

  • private (String|nil) (defaults to: nil) —

    the private key to use when signing requests



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/battlenet/battlenet.rb', line 88

def initialize(region = :us, public = nil, private = nil)
  @public = public
  @private = private

  @proto = @public && @private ? "https://" : "http://"
  @endpoint = '/api/wow'
  @domain = case region
  when :us
    'us.battle.net'
  when :eu
    'eu.battle.net'
  when :kr
    'kr.battle.net'
  when :tw
    'tw.battle.net'
  when :cn
    'battlenet.com.cn'
  else
    raise "Invalid region: #{region.to_s}"
  end

  @base_uri = "#{@proto}#{@domain}#{@endpoint}"
  self.class.base_uri @base_uri
end

Class Attribute Details

.fail_silently ⇒ boolean

Whether or not to raise exceptions on error responses from the API endpoint. A value of false causes exceptions to be raised. Defaults to false.

Returns:

  • (boolean) 


71
72
73
 
# File 'lib/battlenet/battlenet.rb', line 71

def fail_silently
  @fail_silently
end

.locale ⇒ String|nil

The locale to use for API calls. Defaults to nil, which makes requests with no locale parameter set.

Returns:

  • (String|nil) 


77
78
79
 
# File 'lib/battlenet/battlenet.rb', line 77

def locale
  @locale
end

Instance Method Details

#fullpath(path) ⇒ String (private)

Returns the full URI for the given path based on the API endpoint set (varies by region).

Returns:

  • (String) —

    the full URI for the path



130
131
132
 
# File 'lib/battlenet/battlenet.rb', line 130

def fullpath(path)
  "#{@endpoint}#{path}"
end

#get(path, params = {}) ⇒ Object

Signs and performs an HTTP GET request. The request is only signed if a public and private key were provided during object instantiation.

Parameters:

  • path (String) —

    the path to GET

  • params (Hash) (defaults to: {}) —

    options to be turned into query string parameters

Returns:

  • (Object) —

    the response object from HTTParty

Raises:

  • Battlenet::ApiException if the response has a 4xx or 5xx response and Battlenet.fail_silently is false

See Also:



121
122
123
 
# File 'lib/battlenet/battlenet.rb', line 121

def get(path, params = {})
  make_request :get, path, params
end

#make_request(verb, path, params = {}) ⇒ Object (private)

Signs and performs an HTTP request. The request is only signed if a public and private key were provided during object instantiation.

Parameters:

  • verb (Symbol) —

    the HTTP verb to perform

  • path (String) —

    the path to GET

  • params (Hash) (defaults to: {}) —

    options to be turned into query string parameters

Returns:

  • (Object) —

    the response object from HTTParty

Raises:

  • Battlenet::ApiException if the response has a 4xx or 5xx response and Battlenet.fail_silently is false

See Also:



145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/battlenet/battlenet.rb', line 145

def make_request(verb, path, params = {})
  options = {}
  headers = {}

  if @public && @private
    now = Time.now
    signed = sign_request verb, path, now
    headers.merge!({
      "Authorization" => "BNET #{@public}:#{signed}",
      "Date" => now.httpdate
    })
  end

  options[:headers] = headers unless headers.empty?
  options[:query]   = params unless params.empty?

  if Battlenet.locale
    options[:query] ||= {}
    options[:query].merge!({ :locale => Battlenet.locale })
  end

  response = self.class.send(verb, path, options)
  process_response response
end

#process_response(response) ⇒ Object (private) 



170
171
172
173
174
175
 
# File 'lib/battlenet/battlenet.rb', line 170

def process_response(response)
  if response.code.to_s =~ /^(4|5)/ && Battlenet.fail_silently == false
    raise Battlenet::ApiException.new(response)
  end
  response
end

#sign_request(verb, path, time) ⇒ String (private)

Signs an HTTP request.

Parameters:

  • verb (Symbol) —

    the HTTP verb for the request being signed

  • path (String) —

    the path for the rquest being signed

  • time (Time) —

    the time to use when signing the request

Returns:

  • (String) —

    value to be used as the final portion of the Authorization HTTP header

See Also:



184
185
186
187
 
# File 'lib/battlenet/battlenet.rb', line 184

def sign_request(verb, path, time)
  auth = Battlenet::Authentication.new @private
  auth.sign verb, fullpath(path), time
end