vainglory-api 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: df230271ab484d16bf6be0704412c6c738adbc50
-  data.tar.gz: 4e8f5f358709b76ceb99f394cd0d5d1d40a8dad9
+  metadata.gz: 77529bebc4c054437e5568b468cab881c10e4c45
+  data.tar.gz: 0e605b5f0f1291c6b5ad72b5883c1b2a60087605
 SHA512:
-  metadata.gz: 98837caf5b1f58a0ec473f87585b972863048079ae6ffb00e7d83ac7dd937b37ae297ff4d8004c194fe73e7b9e6e160170f75261b2be8cc5898c2229d8f9e294
-  data.tar.gz: 3dfcf7e3aa98c1f9392c9900de72d10ee704c76d1c2564c7e7042013217a0f407406f166d7a50d00c689c415af6b0125397415a46a29528952fde455e3a9e205
+  metadata.gz: e3b5a08e3ee00f30e09f182b074a090f5944a74c863e8c0e0b38743394667f4d52b250216ab0f4f6d8e0bc5d463cd02a533486c86efeba5cbd3592955fd6da38
+  data.tar.gz: dd326e89fe122bbdaa7fe6cb92c5e7c29cdd49e4a64d5914b7b31f74b766b7e4f823824971009a4c832732d60f9fa8eb630f6b7559a9cafaf8c1289d2b4d032a

data/.gitignore

@@ -0,0 +1,50 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+.env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+# .rvmrc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,2 @@
+Documentation:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+rvm:
+  - 2.4.0
+  - 2.3.3
+  - 2.2
+  - 2.1
+  - 2.0
+sudo: false
+gemfile: Gemfile
+script: bundle exec rspec spec
+addons:
+  code_climate:
+    repo_token: d20c1b4862616550a65962ceecf0299c70a844cbce54a230b5234804ac2725dc
+after_success:
+  - bundle exec codeclimate-test-reporter

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+### 0.0.3 - 2017-03-28
+- Ruby version >= 2.0 is required
+
+### 0.0.2 - 2017-03-28
+
+### 0.0.1 - 2017-03-28

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Chet Bortz
+
+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,112 @@
+# vainglory-api
+[![Gem Version](https://badge.fury.io/rb/vainglory-api.svg)](https://badge.fury.io/rb/vainglory-api)
+[![Travis CI](https://travis-ci.org/cbortz/vainglory-api-ruby.svg?branch=master)](https://travis-ci.org/cbortz/vainglory-api-ruby)
+[![Code Climate](https://codeclimate.com/github/cbortz/vainglory-api-ruby/badges/gpa.svg)](https://codeclimate.com/github/cbortz/vainglory-api-ruby)
+[![Test Coverage](https://codeclimate.com/github/cbortz/vainglory-api-ruby/badges/coverage.svg)](https://codeclimate.com/github/cbortz/vainglory-api-ruby/coverage)
+[![Inline docs](http://inch-ci.org/github/cbortz/vainglory-api-ruby.svg?branch=master)](http://inch-ci.org/github/cbortz/vainglory-api-ruby)
+
+- [YARD Documentation](http://www.rubydoc.info/github/cbortz/vainglory-api-ruby)
+- [Official Vainglory API Documentation](https://developer.vainglorygame.com/docs)
+
+---
+
+## Getting Started
+
+VaingloryAPI works with Ruby 2.0 onwards. Please refer to the [YARD Documentation](http://www.rubydoc.info/github/cbortz/vainglory-api-ruby) for a better understanding of how everything works.
+
+### Installation
+
+You can add it to your Gemfile with:
+
+```ruby
+gem 'vainglory-api'
+```
+
+Then run `bundle install`
+
+You can also install it manually with:
+
+```bash
+gem install vainglory-api
+```
+
+### Usage
+
+You can create an instance of the API client by initializing with your API key and [specified region](https://developer.vainglorygame.com/docs#regions) (`na` is the default):
+
+```ruby
+client = VaingloryAPI.new('YOUR_API_KEY', 'na')
+```
+
+#### Helper Attributes
+
+All client methods return an `OpenStruct` object containing the response attributes with some additional helper attributes.
+
+```ruby
+response = client.samples
+
+response.code     # The HTTP response code
+response.success? # Returns true if the response code is less than 300
+response.raw      # The complete HTTP response
+```
+
+#### Rate Limits
+
+Each request will return data about your rate limits.
+
+```ruby
+response.rate_limit     # Request limit per day / per minute
+response.rate_remaining # The number of requests left for the time window
+response.rate_reset     # The remaining window before the rate limit is refilled in UTC epoch nanoseconds.
+```
+
+More information: https://developer.vainglorygame.com/docs#rate-limits
+
+#### Filtering
+
+Currently, filters are supported by these client methods:
+
+- `VaingloryAPI::Client#matches`
+- `VaingloryAPI::Client#samples`
+
+You can pass filters in as a hash using the exact Query Parameter key names outlined in the [Vainglory API Documentation](https://developer.vainglorygame.com/docs).
+
+```ruby
+# Example matches request with filter
+client.matches('filter[playerNames]' => 'boombastic04,IHaveNoIdea')
+```
+
+#### Methods
+
+To get __multiple matches__:
+
+```ruby
+client.matches
+```
+
+To get __single match data__, you must provide the ID of a match:
+
+```ruby
+client.match('37f94e56-1360-11e7-a250-062445d3d668')
+```
+
+You can search for data of __one or more players__ by passing their in-game names (IGNs):
+
+```ruby
+client.players('boombastic04', 'IHaveNoIdea')
+```
+
+To get data about a __single player__, you must provide the ID of the player:
+
+```ruby
+client.player('6abb30de-7cb8-11e4-8bd3-06eb725f8a76')
+```
+
+To get __Telemetry__ data, you must provide the data URL:
+
+```ruby
+client.telemetry('https://gl-prod-us-east-1.s3.amazonaws.com/assets/semc-vainglory/na/2017/03/28/03/07/b0bb7faf-1363-11e7-b11e-0242ac110006-telemetry.json')
+```
+
+## License
+[MIT License](LICENSE). Copyright 2017 Chet Bortz

data/lib/vainglory_api.rb

@@ -1,110 +1,21 @@
-require 'json'
-require 'ostruct'
-require 'openssl'
-require 'net/http'
-
-class VaingloryAPI
-  BASE_URL = "https://api.dc01.gamelockerapp.com"
-
-  def initialize(api_key, region = "na")
-    @api_key = api_key
-    @region = region
-  end
-
-  def samples(filter_params = {})
-    get_request(endpoint_uri("shards/#{@region}/samples", filter_params))
-  end
-
-  def matches(filter_params = {})
-    get_request(endpoint_uri("shards/#{@region}/matches", filter_params))
-  end
-
-  def match(match_id)
-    get_request(endpoint_uri("shards/#{@region}/matches/#{match_id}"))
-  end
-
-  def players(*names)
-    filter_params = {"filter[playerNames]" => names.join(',')}
-    get_request(endpoint_uri("shards/#{@region}/players", filter_params))
-  end
-
-  def player(player_id)
-    get_request(endpoint_uri("shards/#{@region}/players/#{player_id}"))
-  end
-
-  def telemetry(url)
-    get_request(URI(url), true, false)
-  end
-
-  def teams(filter_params = {})
-    raise(NotImplementedError, "Coming soon!")
-  end
-
-  def team(team_id)
-    raise(NotImplementedError, "Coming soon!")
-  end
-
-  def link(link_id)
-    raise(NotImplementedError, "Coming soon!")
-  end
-
-  def status
-    get_request_without_headers(endpoint_uri('status'))
-  end
-
-  private
-
-  def get_request_without_headers(uri)
-    get_request(uri, false)
-  end
-
-  def get_request(uri, with_headers = true, with_auth = true)
-    req = Net::HTTP::Get.new(uri)
-    req = apply_headers(req, with_auth) if with_headers
-
-    request(uri, req)
-  end
-
-  def apply_headers(req, with_auth = true)
-    req['Authorization'] = "Bearer #{@api_key}" if with_auth
-    req['X-TITLE-ID'] = "semc-vainglory"
-    req['Accept'] = "application/vnd.api+json"
-
-    req
-  end
-
-  def request(uri, req)
-    http              = Net::HTTP.new(uri.host, uri.port)
-    http.verify_mode  = OpenSSL::SSL::VERIFY_NONE
-    http.use_ssl      = true
-
-    response(http.request(req))
-  end
-
-  def endpoint_uri(path, filter_params = {})
-    uri = URI(endpoint_url(path))
-    uri.query = URI.encode_www_form(filter_params)
-
-    uri
-  end
-
-  def endpoint_url(path)
-    [BASE_URL, path].join('/')
-  end
-
-  def response(response_data)
-    parsed_body = JSON.parse(response_data.body, object_class: OpenStruct)
-    parsed_code = response_data.code.to_i
-
-    OpenStruct.new({
-      code:           parsed_code,
-      success?:       parsed_code < 300,
-      rate_limit:     response_data['X-RateLimit-Limit'].to_i,
-      rate_remaining: response_data['X-RateLimit-Remaining'].to_i,
-      rate_reset:     response_data['X-RateLimit-Reset'].to_i,
-      data:           parsed_body.respond_to?(:data) ? parsed_body.data : parsed_body,
-      error:          parsed_body.respond_to?(:error)? parsed_body.error : nil,
-      raw:            response_data
-    })
-  end
+require 'vainglory_api/client'
+
+# A Ruby libary wrapper for the Vainglory API
+#
+# @author Chet Bortz
+module VaingloryAPI
+  # Alias for VaingloryAPI::Client constructor
+  #
+  # @overload new(api_key, region)
+  #   @param api_key (String) your Vainglory API key
+  #   @param region (String) the short name for your specified Region shard
+  # @param (see VaingloryAPI::Client#initialize)
+  # @example Initialize a new client
+  #   client = VaingloryAPI.new('API_KEY', 'na')
+  # @return [VaingloryAPI::Client] an instance of the client
+  # @see VaingloryAPI::Client#initialize
+  def new(*args)
+    Client.new(*args)
+  end
+  module_function :new
 end

data/lib/vainglory_api/client.rb

@@ -0,0 +1,244 @@
+require 'json'
+require 'ostruct'
+require 'openssl'
+require 'net/http'
+
+module VaingloryAPI
+  # Used to interface with the official Vainglory API
+  #
+  # @see https://developer.vainglorygame.com/docs Vainglory API Documentation
+  # @see https://developer.vainglorygame.com/docs#payload Vainglory API "Payload"
+  # @see https://developer.vainglorygame.com/docs#rate-limits Vainglory API "Rate Limits"
+  class Client
+    # The base URL used for most requests
+    BASE_URL = 'https://api.dc01.gamelockerapp.com'.freeze
+
+    # A new instance of Client.
+    #
+    # @param (String) api_key your Vainglory API key
+    # @param (String) region the short name for your specified Region shard
+    # @example Initialize a new client
+    #   client = VaingloryAPI::Client.new('API_KEY', 'na')
+    # @return [Client] a new instance of the client
+    def initialize(api_key, region = 'na')
+      @api_key = api_key
+      @region = region
+    end
+
+    # Gets batches of random match data
+    #
+    # @param [Hash] filter_params the parameters used to filter results
+    # @option filter_params [String] 'page[offset]' (0) Allows paging over results
+    # @option filter_params [String] 'page[limit]' (50) Values less than 50 and great than 2 are supported.
+    # @option filter_params [String] 'sort' (createdAt) By default, Matches are sorted by creation time ascending.
+    # @option filter_params [String] 'filter[createdAt-start]' (3hrs ago)  Must occur before end time. Format is iso8601
+    # @option filter_params [String] 'filter[createdAt-end]' (Now) Queries search the last 3 hrs. Format is iso8601
+    # @example Get samples
+    #   client = VaingloryAPI::Client.new('API_KEY', 'na')
+    #   client.samples
+    # @return [OpenStruct] the response and metadata
+    # @see https://developer.vainglorygame.com/docs#samples Vainglory API "Samples"
+    # @see https://developer.vainglorygame.com/docs#pagination Vainglory API "Pagination"
+    # @see https://developer.vainglorygame.com/docs#sorting Vainglory API "Sorting"
+    def samples(filter_params = {})
+      get_request(endpoint_uri("shards/#{@region}/samples", filter_params))
+    end
+
+    # Gets data from matches (multiple)
+    #
+    # @param [Hash] filter_params the parameters used to filter results
+    # @option filter_params [String] 'page[offset]' (0) Allows paging over results
+    # @option filter_params [String] 'page[limit]' (50) Values less than 50 and great than 2 are supported.
+    # @option filter_params [String] 'sort' (createdAt) By default, Matches are sorted by creation time ascending.
+    # @option filter_params [String] 'filter[createdAt-start]' (3hrs ago)  Must occur before end time. Format is iso8601
+    # @option filter_params [String] 'filter[createdAt-end]' (Now) Queries search the last 3 hrs. Format is iso8601
+    # @option filter_params [String] 'filter[playerNames]' Filters by player name, separated by commas.
+    # @option filter_params [String] 'filter[playerIds]' Filters by player Id, separated by commas.
+    # @option filter_params [String] 'filter[teamNames]' Filters by team names. Team names are the same as the in game team tags.
+    # @option filter_params [String] 'filter[gameMode]' Filters by Game Mode
+    # @example Get matches
+    #   client = VaingloryAPI::Client.new('API_KEY', 'na')
+    #   client.matches
+    # @example Get matches with a filter
+    #   client = VaingloryAPI::Client.new('API_KEY', 'na')
+    #   client.matches('filter[playerNames]' => 'player_name')
+    # @return [OpenStruct] the response and metadata
+    # @see https://developer.vainglorygame.com/docs#get-a-collection-of-matches Vainglory API "Get a collection of Matches"
+    # @see https://developer.vainglorygame.com/docs#rosters Vainglory API "Rosters"
+    # @see https://developer.vainglorygame.com/docs#match-data-summary Vainglory API "Match Data Summary"
+    # @see https://developer.vainglorygame.com/docs#pagination Vainglory API "Pagination"
+    # @see https://developer.vainglorygame.com/docs#sorting Vainglory API "Sorting"
+    def matches(filter_params = {})
+      get_request(endpoint_uri("shards/#{@region}/matches", filter_params))
+    end
+
+    # Gets data for a single match
+    # @param [String] match_id the ID of the requested match
+    # @example Get a single match
+    #   client = VaingloryAPI::Client.new('API_KEY', 'na')
+    #   client.match('MATCH_ID')
+    #
+    # @return [OpenStruct] the response and metadata
+    # @see https://developer.vainglorygame.com/docs#get-a-single-match Vainglory API "Get a single Match"
+    # @see https://developer.vainglorygame.com/docs#rosters Vainglory API "Rosters"
+    # @see https://developer.vainglorygame.com/docs#match-data-summary Vainglory API "Match Data Summary"
+    def match(match_id)
+      get_request(endpoint_uri("shards/#{@region}/matches/#{match_id}"))
+    end
+
+    # Gets data about players (one or more)
+    #
+    # @param [String] player_name the in-game name (IGN) of a player
+    # @param [String] additional_player_names additional IGNs for search for
+    # @example Search for a player
+    #   client = VaingloryAPI::Client.new('API_KEY', 'na')
+    #   client.players('player_name')
+    # @example Search for multiple players
+    #   client = VaingloryAPI::Client.new('API_KEY', 'na')
+    #   client.players('player_name', 'player_name2')
+    # @return [OpenStruct] the response and metadata
+    # @see https://developer.vainglorygame.com/docs#get-a-collection-of-players Vainglory API "Get a collection of players"
+    def players(player_name, *additional_player_names)
+      player_names = [player_name].concat(additional_player_names)
+      filter_params = { 'filter[playerNames]' => player_names.join(',') }
+      get_request(endpoint_uri("shards/#{@region}/players", filter_params))
+    end
+
+    # Gets data for a single player
+    #
+    # @param [String] player_id the ID of the requested player
+    # @example Get a single player
+    #   client = VaingloryAPI::Client.new('API_KEY', 'na')
+    #   client.match('PLAYER_ID')
+    # @return [OpenStruct] the response and metadata
+    # @see https://developer.vainglorygame.com/docs#get-a-single-player Vainglory API "Get a single Player"
+    def player(player_id)
+      get_request(endpoint_uri("shards/#{@region}/players/#{player_id}"))
+    end
+
+    # Gets telemtry data from a specified URL
+    #
+    # @param [String] url the URL of the requested Telemetry data
+    # @example Get telemetry data
+    #   client = VaingloryAPI::Client.new('API_KEY', 'na')
+    #   client.telemetry('TELEMETRY_URL')
+    # @return [OpenStruct] the response and metadata
+    # @see https://developer.vainglorygame.com/docs#telemetry Vainglory API "Telemetry"
+    def telemetry(url)
+      get_request(URI(url), true, false)
+    end
+
+    # Gets aggregated lifetime information about teams (multiple)
+    #
+    # @param [Hash] _filter_params the parameters used to filter results
+    # @option _filter_params [String] 'filter[teamNames]' Filters by team name
+    # @option _filter_params [String] 'filter[teamIds]' Filters by team ID
+    # @raise [NotImplementedError] this endpoint is not yet available
+    # @see https://developer.vainglorygame.com/docs#teams-coming-soon Vainglory API "Get a collection of Teams"
+    def teams(_filter_params = {})
+      raise(NotImplementedError, 'Coming soon!')
+    end
+
+    # Gets aggregated lifetime information about a single team
+    #
+    # @raise [NotImplementedError] this endpoint is not yet available
+    # @see https://developer.vainglorygame.com/docs#get-a-single-team Vainglory API "Get a single Team"
+    def team(_team_id)
+      raise(NotImplementedError, 'Coming soon!')
+    end
+
+    # Checks to see if a link object exists for a given code
+    #
+    # @raise [NotImplementedError] this endpoint is not yet available
+    # @see https://developer.vainglorygame.com/docs#links-coming-soon Vainglory API "Links"
+    def link(_link_id)
+      raise(NotImplementedError, 'Coming soon!')
+    end
+
+    # Gets current API version and release date
+    #
+    # @example Get the API's status information
+    #   client = VaingloryAPI::Client.new('API_KEY', 'na')
+    #   client.status
+    # @return [OpenStruct] the response and metadata
+    # @see https://developer.vainglorygame.com/docs#versioning Vainglory API "Versioning"
+    def status
+      get_request_without_headers(endpoint_uri('status'))
+    end
+
+    private
+
+    def get_request_without_headers(uri)
+      get_request(uri, false)
+    end
+
+    def get_request(uri, with_headers = true, with_auth = true)
+      req = Net::HTTP::Get.new(uri)
+      req = apply_headers(req, with_auth) if with_headers
+
+      request(uri, req)
+    end
+
+    def apply_headers(req, with_auth = true)
+      req['Authorization'] = "Bearer #{@api_key}" if with_auth
+      req['X-TITLE-ID'] = 'semc-vainglory'
+      req['Accept'] = 'application/vnd.api+json'
+
+      req
+    end
+
+    def request(uri, req)
+      http              = Net::HTTP.new(uri.host, uri.port)
+      http.verify_mode  = OpenSSL::SSL::VERIFY_NONE
+      http.use_ssl      = true
+
+      response(http.request(req))
+    end
+
+    def endpoint_uri(path, filter_params = {})
+      uri = URI(endpoint_url(path))
+      uri.query = URI.encode_www_form(filter_params)
+
+      uri
+    end
+
+    def endpoint_url(path)
+      [BASE_URL, path].join('/')
+    end
+
+    def response(response_data)
+      response_object = serialize_response_data(response_data.body)
+      metadata        = serialize_response_metadata(response_data)
+
+      # Add metadata members to response_object
+      metadata.each do |k, v|
+        response_object[k] = v
+      end
+
+      response_object
+    end
+
+    def serialize_response_metadata(response_data)
+      response_code = response_data.code.to_i
+
+      {
+        code:           response_code,
+        success?:       response_code < 300,
+        rate_limit:     response_data['X-RateLimit-Limit'].to_i,
+        rate_remaining: response_data['X-RateLimit-Remaining'].to_i,
+        rate_reset:     response_data['X-RateLimit-Reset'].to_i,
+        raw:            response_data
+      }
+    end
+
+    def serialize_response_data(raw_response_body)
+      data = JSON.parse(raw_response_body, object_class: OpenStruct)
+
+      if data.is_a?(Array)
+        OpenStruct.new(data: data)
+      else
+        data
+      end
+    end
+  end
+end