/rbattlenet

A wrapper gem for the Blizzard's Battle.net API

Primary LanguageRubyMIT LicenseMIT

RBattlenet

A Ruby gem that wraps Blizzard's Game Data and Profile APIs.

Please note, this project is not actively maintained, but PRs are always welcome!

Installation

Add this line to your application's Gemfile:

gem 'rbattlenet'

Usage

Step 1. Setting your Battle.net API Key

Your private Battle.net API key must be present in order to get a valid Battle.net API response. Before any requests are made, your API key must be set like so:

client_id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client_secret = "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"

RBattlenet.authenticate(client_id: client_id, client_secret: client_secret)

Step 2. Changing default options (Optional)

Your region and locale defaults to EU and en_GB respectively. However, these can be changed like so:

RBattlenet.set_options(region: "us", locale: "en_US")

Singular requests will be returned as a RBattlenet::Result object. Requests with an array passed in will be returned as a RBattlenet::ResultCollection object by default. If you want to simply receive the raw HTTP response or the response as a Hash you can set that like so:

RBattlenet.set_options(response_type: :struct) # Default
RBattlenet.set_options(response_type: :hash)
RBattlenet.set_options(response_type: :raw)

Step 3. Call the API methods to request data

item = RBattlenet::Wow::Item.find(18803)

item.name # => "Finkle's Lava Dredger"

You can pass in an Array to every endpoint. Requests will be made in parallel automatically:

collection = RBattlenet::Wow::Item.find([18803, 18804])

collection.results.map(&:name) # => ["Finkle's Lava Dredger", "Lord Grayson's Satchel"]

For some endpoints you can pass in fields to automatically (in parallel) retrieve resources that belong to them:

character = RBattlenet::Wow::Character.find(realm: "stormrage", name: "sheday", fields: [:mounts, :titles])

character.name # => "Sheday"
character.titles.active_title.name # => "Famed Slayer of the Harbinger"
character.mounts.first.name # => "Black War Bear"

Step 4. Error handling

Each RBattlenet::Result object has a status_code property. When the code is not 200, the raw HTTP response is included (response property) and it'll be a RBattlenet::EmptyResult object instead. RBattlenet::ResultCollection objects can contain both Result and EmptyResult objects simultaneously. Exceptions are not raised for non-200 responses.

Client side exceptions will be raised if there are issues, for example:

characters = RBattlenet::Wow::Character.all

# => RBattlenet::Errors::IndexNotSupported (Retrieving all entities of this endpoint is not supported)

Profile API

The Account Profile API needs an access token acquired via the Authorization Code Flow.

It concerns the following requests:

  • RBattlenet::Wow::Profile::User
  • RBattlenet::Wow::Profile::ProtectedSummary
  • RBattlenet::Wow::Profile::MountsCollection
  • RBattlenet::Wow::Profile::PetsCollection

Testing

Test against the stored VCR cassettes

bundle exec rspec spec/ # Execute all the tests
bundle exec rspec spec/lib/wow/character_spec.rb # Execute only the character_spec tests

If there is no VCR cassette for the test

RECORD_CASSETTE=1 CLIENT_ID=<your_id> CLIENT_SECRET=<your_secret> bundle exec rspec

If you wish to test against the real API and bypass the :

REAL_CONNECTIONS=1 CLIENT_ID=<your_id> CLIENT_SECRET=<your_secret> bundle exec rspec

Documentation

Some of the most commonly used endpoints are listed here; you can find examples for every single endpoint in the spec files.

Hearthstone

World of Warcraft

World of Warcraft Classic

Starcraft 2

Diablo 3

Hearthstone

https://develop.battle.net/documentation/api-reference/hearthstone-game-data-api

Cards

RBattlenet::Hearthstone::Card.find("52119-arch-villain-rafaam")

Battlenet::Hearthstone::Card.find(manaCost: 1, attack: 1, health: 1)

Decks

RBattlenet::Hearthstone::Deck.find("AAECAQcG+wyd8AKS+AKggAOblAPanQMMS6IE/web8wLR9QKD+wKe+wKz/AL1gAOXlAOalAOSnwMA")

Metadata

RBattlenet::Hearthstone::Metadata.all

RBattlenet::Hearthstone::Metadata.find(:sets)

World of Warcraft

Achievement

achievement = RBattlenet::Wow::Achievement.find(2144)

Character

RBattlenet::Wow::Character.find(realm: "stormrage", name: "sheday")

RBattlenet::Wow::Character.find(realm: "stormrage", name: "sheday", fields: [:achievements, :mounts])

Supported fields: achievements, appearance, equipment, hunter_pets, keystones, media, mounts, pets, pvp_summary, reputations, specializations, statistics, status, titles

Guild

RBattlenet::Wow::Guild.find(realm: "stormrage", name: "avalerion")

RBattlenet::Wow::Guild.find(realm: "stormrage", name: "avalerion", fields: [:roster])

Supported fields: roster, achievements

Item

RBattlenet::Wow::Item.find(11081)

Mount

RBattlenet::Wow::Mount.find(304)

RBattlenet::Wow::Mount.all

Pet

RBattlenet::Wow::Pet.find(405)

RBattlenet::Wow::Pet.all

Mythic Keystone Leaderboard

RBattlenet::Wow::MythicKeystoneLeaderboard.find(connected_realm_id: 509, dungeon_id: 244, period: 682)

World of Warcraft Classic

Creature

RBattlenet::Wow::Classic::Creature.find(30)

Item

RBattlenet::Wow::Classic::Item.find(19019)

Starcraft 2

Profile

RBattlenet::Sc2::Profile.find(region_id: 2, realm_id: 1, id: 2137104)

RBattlenet::Sc2::Legacy::Profile.find(region_id: 2, realm_id: 1, id: 2137104)

Ladders

RBattlenet::Sc2::Legacy::ProfileLadders.find(region_id: 2, realm_id: 1, id: 2137104)

Match history

RBattlenet::Sc2::Legacy::ProfileMatchHistory.find(region_id: 2, realm_id: 1, id: 2137104)

Ladder

RBattlenet::Sc2::Legacy::Ladder.find(region_id: 2, id: 2200)

Diablo 3

Hero

RBattlenet::D3::Hero.find(battletag: "Battle#tag", id: 104729462)

Item

RBattlenet::D3::Item.find("corrupted-ashbringer-Unique_Sword_2H_104_x1")

Contributing

  1. Fork it ( https://github.com/[my-github-username]/rbattlenet/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request