battlenet 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.rvmrc

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in battlenet.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 Brandon Tilley
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,117 @@
+        __ )          |    |    |                     |
+        __ \    _` |  __|  __|  |   _ \  __ \    _ \  __|
+        |   |  (   |  |    |    |   __/  |   |   __/  |
+       ____/  \__,_| \__| \__| _| \___| _|  _| \___| \__|
+
+    A Ruby library for the Battle.net Community Platform API
+
+Battlenet is a Ruby library that exposes Blizzard's [Community Platform API](http://us.battle.net/wow/en/forum/topic/2369881371).
+
+Installing
+==========
+
+Battlenet is available as a Ruby gem. Install it via
+
+    [sudo] gem install battlenet
+
+Use
+===
+
+In general, the API is split into several sub-modules, each corresponding to an entity in Blizzard's API. For example, methods for using the Realm Status API are located in the module `Battlenet::API::Realm`. Methods on the model allow you to fetch certain information about the given entity. Arguments passed to the methods allow you to specify query string parameters. As an example, here are some sample API calls and the URL they translate into.
+
+    Battlenet::API::Realm.status
+     # => "http://us.battle.net/api/wow/realm/status"
+    Battlenet::API::Realm.status :realm => "Nazjatar"
+     # => "http://us.battle.net/api/wow/realm/status?realm=Nazjatar"
+    Battlenet::API::Realm.status :realm => ["Nazjatar", "Shadowsong"]
+     # => "http://us.battle.net/api/wow/realm/status?realm=Nazjatar&realm=Shadowsong"
+
+Calls to the methods return an array of Hashes, and each hash contains the data for the queried resources. The attributes can be accessed via Strings or Symbols (you can set this to Strings only via `Battlenet::API.set_option`, see below).
+
+**Note**: This is all subject to change depending on how Blizzard architects the rest of their API.
+
+Configuration
+=============
+
+You may pass multiple options to Battlenet to change its behavior.
+
+Region
+------
+
+By default, the region is set to `:us`, which corresponds to the US Battle.net API. You may set this to any symbol to force the library to use that region's API.
+
+    Battlenet::API.set_option(:region, :eu)
+
+HTTP Adapter
+------------
+
+Battlenet supports multiple adapters for fetching API data over the Internet. By default, it uses Ruby's built-in `Net::HTTP` library. If you wish to use a different adapter, specify it like this:
+
+    Battlenet::API.set_option(:http_adapter, :typhoeus)
+
+The following adapters are currently supported (more may be added later):
+
+* `:net_http` - Ruby's `Net::HTTP` library
+* `:typhoeus` - [Typhoeus](https://github.com/dbalatero/typhoeus)
+
+Note that the adapter must be set before any API calls are made.
+
+Currently Supported APIs
+========================
+
+Currently, the following APIs are supported. More will be added as Blizzard expands their API library.
+
+ * [Realm Status API](http://us.battle.net/wow/en/forum/topic/2369741469)
+
+Realm Status API
+----------------
+
+    api = Battlenet::API::Realm
+
+    # Getting data for all realms
+    all_realms = api.status
+    # Getting data for specific realms
+    realms     = api.status :realm => ["Nazjatar", "Shadowsong"]
+    # Getting data for one realm
+    realm      = api.status :realm => "Nazjatar"
+
+    # Getting data about a realm
+    realms.first["population"]
+     # => "low"
+    realms.first["queue"]
+     # => false
+
+Contributing
+============
+
+If you would like to contribute to the project, please feel free to do so. Just fork the project, commit your changes (preferably to a new branch), and then send me a pull request via GitHub. Be sure to add tests for your feature or fix.
+
+Please do not change the contents of the `VERSION` file, or if you do, do so in a separate commit so that I can cherry-pick around it.
+
+License
+=======
+
+Battlenet is released under the MIT license.
+
+    Copyright (c) 2011 Brandon Tilley
+
+    Permission is hereby granted, free of charge, to any person
+    obtaining a copy of this software and associated documentation
+    files (the "Software"), to deal in the Software without
+    restriction, including without limitation the rights to use,
+    copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following
+    conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+    OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,9 @@
+require 'bundler'
+require 'rspec/core/rake_task'
+
+Bundler::GemHelper.install_tasks
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = ['--color', '-f progress', '-r ./spec/spec_helper.rb']
+  t.pattern = 'spec/**/*_spec.rb'
+  t.fail_on_error = false
+end

data/battlenet.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require 'battlenet/version'
+
+Gem::Specification.new do |s|
+  s.name        = "battlenet"
+  s.version     = Battlenet::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Brandon Tilley"]
+  s.email       = ["brandon@brandontilley.com"]
+  s.homepage    = ""
+  s.summary     = %q{Easily consume Blizzard's Community Platform API.}
+  s.description = %q{Easily consume Blizzard's Community Platform API.}
+
+  if s.respond_to?(:add_development_dependency)
+    s.add_development_dependency "rspec"
+  end
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/battlenet.rb

@@ -0,0 +1,2 @@
+require 'battlenet/api'
+require 'battlenet/api/realm'

data/lib/battlenet/adapter/abstract_adapter.rb

@@ -0,0 +1,11 @@
+module Battlenet
+  module Adapter
+    class NotImplementedException < Exception; end
+
+    class AbstractAdapter
+      def get(url)
+        raise NotImplementedException.new("Please implement #get in your adapter")
+      end
+    end
+  end
+end

data/lib/battlenet/adapter/net_http.rb

@@ -0,0 +1,14 @@
+require 'battlenet/adapter/abstract_adapter'
+require 'net/http'
+
+module Battlenet
+  module Adapter
+    class NetHTTP < AbstractAdapter
+      def get(url)
+        uri      = URI.parse url
+        response = Net::HTTP.get_response uri
+        [response.code.to_i, response.body]
+      end
+    end
+  end
+end

data/lib/battlenet/adapter/typhoeus.rb

@@ -0,0 +1,13 @@
+require 'battlenet/adapter/abstract_adapter'
+require 'typhoeus'
+
+module Battlenet
+  module Adapter
+    class Typhoeus < AbstractAdapter
+      def get(url)
+        response = ::Typhoeus::Request.get url
+        [response.code.to_i, response.body]
+      end
+    end
+  end
+end

data/lib/battlenet/adapter_manager.rb

@@ -0,0 +1,47 @@
+module Battlenet
+  module Adapter; end
+
+  module AdapterManager
+    class InvalidAdapter < Exception; end
+
+    extend self
+
+    @adapters = {
+      :net_http => "NetHTTP",
+      :typhoeus => "Typhoeus"
+    }
+
+    def adapters
+      @adapters
+    end
+
+    def fetch(adapter_name)
+      unless adapters.include? adapter_name
+        raise InvalidAdapter.new("#{adapter_name.to_s} is not a valid adapter")
+      end
+
+      adapter_class = adapters[adapter_name]
+      adapter = load_adapter adapter_name, adapter_class
+    end
+
+    private
+
+      def load_adapter(adapter_name, klass_name)
+        begin
+          klass = Battlenet::Adapter.const_get("#{klass_name}", false)
+        rescue NameError
+          begin
+            adapter_file = "battlenet/adapter/#{adapter_name.to_s}"
+            require adapter_file
+            klass = Battlenet::Adapter.const_get("#{klass_name}", false)
+          rescue LoadError
+            raise InvalidAdapter.new("adapter #{klass_name} does not exist, and file #{adapter_file} does not exist")
+          rescue NameError
+            raise InvalidAdapter.new("expected #{adapter_file} to define Battlenet::Adapter::#{klass_name}")
+          end
+        end
+
+        return klass.new
+      end
+  end
+end

data/lib/battlenet/api.rb

@@ -0,0 +1,73 @@
+require 'battlenet/adapter_manager'
+require 'cgi'
+require 'json'
+
+module Battlenet
+  module API
+    class APIError < Exception
+      attr_reader :code, :body
+      def initialize(code, body)
+        @code = code
+        @body = body
+      end
+
+      def to_s
+        "Status: #{code} Body: #{body}"
+      end
+    end
+
+    extend self
+
+    @config = {
+      :indifferent_hashes => true,
+      :http_adapter       => :net_http,
+      :region             => :us
+    }
+
+    def set_option(setting, value)
+      @config[setting] = value
+    end
+
+    def get_option(setting, default = nil)
+      @config[setting] || default
+    end
+
+    def adapter
+      @adapter ||= Battlenet::AdapterManager.fetch get_option(:http_adapter)
+    end
+
+    def base_url
+      region = get_option(:region, :us).to_s
+      "http://#{region}.battle.net/api/wow"
+    end
+
+    def make_api_call(path, query = {})
+      query_string = query.empty? ? '' : make_query_string(query)
+      url = base_url
+      url << (path.start_with?('/') ? '' : '/')
+      url << path
+      url << query_string
+      code, body = get url
+      raise APIError.new(code, body) unless code == 200
+      JSON::parse body
+    end
+
+    def get(url)
+      adapter.get(url)
+    end
+
+    def make_query_string(query)
+      query_string = "?"
+      query.each do |key, value|
+        case value
+        when String
+          query_string << "#{key}=#{CGI.escape value}&"
+        when Array
+          value.each { |v| query_string << "#{key}=#{CGI.escape v}&" }
+        end
+      end
+
+      query_string.chomp("&").chomp("?")
+    end
+  end
+end

data/lib/battlenet/api/realm.rb

@@ -0,0 +1,14 @@
+module Battlenet
+  module API
+    module Realm
+      extend self
+
+      @api = Battlenet::API
+
+      def status(options = {})
+        data = @api.make_api_call 'realm/status', options
+        data["realms"]
+      end
+    end
+  end
+end

data/lib/battlenet/version.rb

@@ -0,0 +1,3 @@
+module Battlenet
+  VERSION = "0.1.0"
+end

data/spec/abstract_adapter_spec.rb

@@ -0,0 +1,15 @@
+require 'battlenet/adapter/abstract_adapter'
+
+describe Battlenet::Adapter::AbstractAdapter do
+  it "has a method 'get'" do
+    subject.should respond_to :get
+  end
+
+  context "#get" do
+    it "is abstract" do
+      lambda {
+        subject.get('fake_url')
+      }.should raise_error Battlenet::Adapter::NotImplementedException
+    end
+  end
+end

data/spec/adapter_manager_spec.rb

@@ -0,0 +1,47 @@
+require 'battlenet/adapter_manager'
+
+describe Battlenet::AdapterManager do
+  it "has a list of adapters" do
+    subject.adapters.should be_a Hash
+  end
+
+  context "#fetch" do
+    it "raises an exception if an invalid adapter is passed" do
+      lambda {
+        subject.fetch(:some_fake_adapter)
+      }.should raise_error Battlenet::AdapterManager::InvalidAdapter
+    end
+
+    it "requires a library file based on the adapter chosen if the class doesn't exist" do
+      subject.should_receive(:require).once.with('battlenet/adapter/net_http')
+      begin
+        subject.fetch(:net_http)
+      rescue Battlenet::AdapterManager::InvalidAdapter
+        # expected
+      end
+    end
+
+    it "raises an error if the adapter class doesn't exist and the library can't be loaded" do
+      old_adapters = subject.adapters
+      subject.instance_variable_set(:@adapters, {:adapter => "SuperAdapter"})
+
+      lambda {
+        subject.fetch(:adapter)
+      }.should raise_error Battlenet::AdapterManager::InvalidAdapter, /does not exist/
+
+      subject.instance_variable_set(:@adapters, old_adapters)
+    end
+
+    it "raises an error if the adapter library is loaded but doesn't define the adapter class" do
+      subject.should_receive(:require).once.with('battlenet/adapter/net_http').and_return(nil)
+      lambda {
+        subject.fetch(:net_http)
+      }.should raise_error Battlenet::AdapterManager::InvalidAdapter, /expected (.*) to define/
+    end
+
+    it "returns an instance of the adapter" do
+      adapter = subject.fetch(:net_http)
+      adapter.should be_a Battlenet::Adapter::NetHTTP
+    end
+  end
+end

data/spec/api_spec.rb

@@ -0,0 +1,115 @@
+require 'battlenet/api'
+
+describe Battlenet::API do
+  context "configuration management" do
+    it "defauls to nil when getting an unset option" do
+      subject.get_option(:a_fake_setting_i_made_up).should be_nil
+    end
+
+    it "returns a passed value if an option is not set" do
+      subject.get_option(:a_fake_setting_i_made_up, "value").should == "value"
+    end
+
+    it "allows setting and retrieving a value" do
+      subject.set_option(:a_fake_setting_i_made_up, "my_value")
+      subject.get_option(:a_fake_setting_i_made_up).should == "my_value"
+    end
+  end
+
+  context "default configuration" do
+    it "defaults to the US region" do
+      subject.get_option(:region).should == :us
+    end
+
+    it "defaults to indifferent hashes" do
+      subject.get_option(:indifferent_hashes).should == true
+    end
+
+    it "defaults to the Net::HTTP library" do
+      subject.get_option(:http_adapter).should == :net_http
+    end
+  end
+
+  context "HTTP adapter" do
+    it "retrieval is via the Adapter module" do
+      adapter = subject.get_option(:http_adapter)
+      Battlenet::AdapterManager.should_receive(:fetch).with(adapter)
+      subject.send(:adapter)
+    end
+
+    it "caches its adapter" do
+      mock_adapter = mock("adapter")
+      Battlenet::AdapterManager.should_receive(:fetch).with(any_args()).and_return(mock_adapter)
+      adapter = subject.send(:adapter)
+      subject.set_option(:http_adapter, :fake_adapter)
+      subject.send(:adapter).should == mock_adapter
+    end
+  end
+
+  it "returns a base URL dependant on the region" do
+    old_region = subject.get_option(:region)
+    subject.set_option(:region, :eu)
+    subject.send(:base_url).should == "http://eu.battle.net/api/wow"
+    subject.set_option(:region, old_region)
+  end
+
+  context "#make_query_string" do
+    it "produces an empty string with an empty hash" do
+      str = subject.send(:make_query_string, {})
+      str.should be_empty
+    end
+
+    it "starts with a question mark" do
+      str = subject.send(:make_query_string, {:first => "value1", :second => "value2"})
+      str.start_with?("?").should == true
+    end
+
+    it "parses a basic hash" do
+      str = subject.send(:make_query_string, {:first => "value1", :second => "value2"})
+      str.should == "?first=value1&second=value2"
+    end
+
+    it "parses a hash with array values" do
+      str = subject.send(:make_query_string, {:first => ["value1", "value2"], :second => "value3"})
+      str.should == "?first=value1&first=value2&second=value3"
+    end
+
+    it "escapes values" do
+      str = subject.send(:make_query_string, {:first => ["value1", "va&lue2"], :second => "val&ue3"})
+      str.should == "?first=value1&first=va%26lue2&second=val%26ue3"
+    end
+  end
+
+  context "#make_api_call" do
+    it "makes a get call with the correct URL" do
+      subject.should_receive(:get).once.with("http://us.battle.net/api/wow/my/path").and_return([200, '{"testing": "value"}'])
+      subject.send(:make_api_call, '/my/path')
+    end
+
+    it "adds a slash to the path if necessary" do
+      subject.should_receive(:get).once.with("http://us.battle.net/api/wow/my/path").and_return([200, '{"testing": "value"}'])
+      subject.send(:make_api_call, 'my/path')
+    end
+
+    it "converts the second parameter into a query string" do
+      options = {:first => ["value1", "va&lue2"], :second => "val&ue3"}
+      query_string = subject.send(:make_query_string, options)
+      subject.should_receive(:get).once.with("http://us.battle.net/api/wow/my/path#{query_string}").and_return([200, '{"testing": "value"}'])
+      subject.send(:make_api_call, 'my/path', options)
+    end
+
+    it "raises an exception on an error" do
+      subject.adapter.should_receive(:get).and_return([404, "not found"])
+      lambda {
+        subject.make_api_call('my/path')
+      }.should raise_error Battlenet::API::APIError, /404 (.*) not found/
+    end
+
+    it "returns the data as JSON" do
+      subject.adapter.should_receive(:get).and_return([200, '{"testing": "value"}'])
+      data = subject.make_api_call('my/path')
+      data.should be_a Hash
+      data["testing"].should == "value"
+    end
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification 
+name: battlenet
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Brandon Tilley
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-15 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: Easily consume Blizzard's Community Platform API.
+email: 
+- brandon@brandontilley.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- battlenet.gemspec
+- lib/battlenet.rb
+- lib/battlenet/adapter/abstract_adapter.rb
+- lib/battlenet/adapter/net_http.rb
+- lib/battlenet/adapter/typhoeus.rb
+- lib/battlenet/adapter_manager.rb
+- lib/battlenet/api.rb
+- lib/battlenet/api/realm.rb
+- lib/battlenet/version.rb
+- spec/abstract_adapter_spec.rb
+- spec/adapter_manager_spec.rb
+- spec/api_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.0
+signing_key: 
+specification_version: 3
+summary: Easily consume Blizzard's Community Platform API.
+test_files: 
+- spec/abstract_adapter_spec.rb
+- spec/adapter_manager_spec.rb
+- spec/api_spec.rb
+- spec/spec_helper.rb