strutta-api 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2d72692a864ae1a19c3bf8761741a79dd505d751
+  data.tar.gz: b0989b6d0d993f3396d2d7f2d59791dd267d5b63
+SHA512:
+  metadata.gz: bac95bc6eaa7f7a19a7d2824ccd2a4a1602b9369b2b5a65fadc64700a6a335b982ce3be9a4cc5ea58936c32588ccb033d386d5579ed8eb9784b04f85d204dec1
+  data.tar.gz: a863c2ec69241f28e429bd3a0279ca3e0aeb03ffd18ada8c7a7b4992af8bf1b43f1b97478098bad2243e27525612d0dfcb04c7821b33711df90d50258d6888e9

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.rubocop.yml

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in strutta-api.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 BlakeTurner
+
+MIT License
+
+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,55 @@
+[![Code Climate](https://codeclimate.com/repos/53d81d1de30ba01f16012d2a/badges/5a6842ba6fe26d49d83b/gpa.png)](https://codeclimate.com/repos/53d81d1de30ba01f16012d2a/feed)
+[![Test Coverage](https://codeclimate.com/repos/53d81d1de30ba01f16012d2a/badges/5a6842ba6fe26d49d83b/coverage.png)](https://codeclimate.com/repos/53d81d1de30ba01f16012d2a/feed)
+
+# Strutta::Api
+
+Official wrapper for the Strutta API
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'strutta-api'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install strutta-api
+
+## Usage
+
+This Gem is designed to have is calls resemble actual API URIs.
+
+For example, if we want to get Rounds in Game 333, we would GET the following URI:
+
+```
+http://api.strutta.com/v2/games/333/rounds
+```
+
+The Gem copies this pattern:
+
+```
+# Initialize
+strutta = Strutta::API.new 'mystruttatoken'
+
+# Get Rounds in Game 333
+strutta.games(333).rounds.get
+```
+
+There are detailed examples for each endpoint found in the Strutta API docs.
+
+## Errors
+
+This Gem Raises exceptions whenever anything other than a `200`, `201` or `204` is returned.
+The errors are defined in lib/strutta/api/errors and generated Strutta::Api#error_map.
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/strutta-api/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 new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task default: :spec
+task test: :spec

data/lib/strutta-api.rb

@@ -0,0 +1,109 @@
+require 'excon'
+require 'json'
+
+require 'strutta-api/api_object.rb'
+require 'strutta-api/entries.rb'
+require 'strutta-api/errors.rb'
+require 'strutta-api/flow.rb'
+require 'strutta-api/games.rb'
+require 'strutta-api/participants.rb'
+require 'strutta-api/points.rb'
+require 'strutta-api/moderation.rb'
+require 'strutta-api/judging.rb'
+require 'strutta-api/rounds.rb'
+require 'strutta-api/version.rb'
+
+module Strutta
+  # Strutta API engine
+  # Handles API requests and errors
+  class API
+    include Strutta::Version
+    attr_accessor :host, :path, :token, :debug, :session
+
+    # Initializes the Strutta API wrapper
+    #
+    # @param token [String] your Strutta API token
+    # @param host [String] Strutta API host URL - used to switched between prod/staging
+    # @param path [String] Strutta API host path - used to switched between versions
+    # @return [Strutta::API] instantiated Strutta API object
+    def initialize(token, host = 'http://strutta-api.herokuapp.com/', path = Version::VERSION_PATH)
+      fail Error, 'You must provide a Strutta API key' unless token
+
+      @host = host
+      @path = path
+      @token = token
+      @session = Excon.new @host
+      @debug = debug
+    end
+
+    # Makes an API call
+    #
+    # @param method [String] the required HTTP method
+    # @param url [String] URL for the call
+    # @param params [Hash] Parameters for the call
+    # @return [Hash] Parsed body of the response
+    def call(method, url, params = {})
+      params = JSON.generate(params)
+      r = @session.send(method, path: "#{@path}#{url}", headers: api_headers, body: params)
+
+      # Delete calls have no JSON return
+      return true if r.status == 204
+
+      # Raise exceptions on error response codes
+      cast_error(r.status, r.body) if r.status >= 400
+
+      JSON.parse(r.body)
+    end
+
+    # Instantiates a Strutta::Games object
+    #
+    # @param id [Integer, nil] the ID of the Strutta game
+    # @return [Strutta::Games] The instantiated Strutta::Games object
+    def games(id = nil)
+      Games.new id, self
+    end
+
+    private
+
+    # Utility: build the Headers hash
+    # @return [Hash] Headers for an API call
+    def api_headers
+      {
+        'Content-Type' => 'application/json',
+        'Authorization' => "Token token=#{@token}"
+      }
+    end
+
+    # Throws exceptions based on HTTP responses
+    #
+    # @param status [Integer] the HTTP response status
+    # @param body [JSON] the HTTP response body
+    # @return [Error] An appropriate exception
+    def cast_error(status, body)
+      error_info = JSON.parse(body)
+      msg = error_info['error'] && error_info['message'] ? "#{error_info['error']} - #{error_info['message']}" : "We received an unexpected error: #{body}"
+      fail error_map(status), msg
+    rescue JSON::ParserError
+      raise Errors::Error, "We received an unexpected error: #{body}"
+    end
+
+    # Map errors to HTTP statuses
+    #
+    # @param status [Integer] the HTTP response status
+    # @return [Error] The associated exception
+    def error_map(status)
+      case status
+      when 401
+        Errors::Unauthorized
+      when 400
+        Errors::BadRequestError
+      when 404
+        Errors::ObjectNotFoundError
+      when 422
+        Errors::UnprocessableEntityError
+      else
+        Errors::Error
+      end
+    end
+  end
+end

data/lib/strutta-api/api_object.rb

@@ -0,0 +1,58 @@
+# Strutta Container
+module Strutta
+  # @abstract
+  # APIObject contains all the HTTP request methods
+  class APIObject
+    attr_accessor :game
+
+    # GET index request
+    # (Uses instance vars of child object to generate resource path)
+    #
+    # @return [Hash] Parsed body of the API response
+    def all(params = {})
+      @game.verify_no_id(@id)
+      @game.all(params, "#{@game.id}/#{@root_path}")
+    end
+
+    # POST request
+    # (Uses instance vars of child object to generate resource path)
+    #
+    # @return [Hash] Parsed body of the API response
+    def create(params = {})
+      @game.verify_no_id(@id)
+      @game.create(params, "#{@game.id}/#{@root_path}")
+    end
+
+    # GET request
+    # (Uses instance vars of child object to generate resource path)
+    #
+    # @return [Hash] Parsed body of the API response
+    def get(params = {})
+      @game.verify_id(@id, Errors::ROUND_ID_REQUIRED)
+      @game.get(params, @root_path)
+    end
+
+    # PATCH request
+    # (Uses instance vars of child object to generate resource path)
+    #
+    # @return [Hash] Parsed body of the API response
+    def update(params = {})
+      @game.verify_id(@id, Errors::ROUND_ID_REQUIRED)
+      @game.update(params, @root_path)
+    end
+
+    # DELETE request
+    # (Uses instance vars of child object to generate resource path)
+    #
+    # @return [Hash] Parsed body of the API response
+    def delete
+      @game.verify_id(@id, Errors::ROUND_ID_REQUIRED)
+      @game.delete(@root_path)
+    end
+
+    # Manually disable a method in child classed
+    def method_disabled(*_)
+      fail Errors::DisabledEndpointError, Errors::METHOD_DISABLED
+    end
+  end
+end

data/lib/strutta-api/entries.rb

@@ -0,0 +1,35 @@
+module Strutta
+  # Entries belong to a Strutta::Games object
+  # Instance methods found in Strutta::APIObject
+  class Entries < APIObject
+    # Initializes the Strutta::Entries object
+    #
+    # @param id [Integer, nil] Entry id
+    # @param game [Strutta::Games] Master Strutta::Games object
+    # @return [Strutta::Entries] instantiated Strutta::Entries object
+    def initialize(id = nil, game)
+      @id = id
+      @game = game
+      @root_path = "entries/#{@id}"
+      @no_id_error = Errors::ENTRY_ID_REQUIRED
+    end
+
+    # GET transition history for Entry (no ID required)
+    # games/:game_id/entries/:id/transitions
+    #
+    # @return [Hash] Parsed body of the API response
+    def transitions(params = {})
+      @game.verify_id(@id, Errors::ENTRY_ID_REQUIRED)
+      @game.get(params, "entries/#{@id}/transitions")
+    end
+
+    # GET leaderboard history for Entries in Points Rounds (no ID required)
+    # games/:game_id/entries/leaderboard
+    #
+    # @return [Hash] Parsed body of the API response
+    def leaderboard(params = {})
+      @game.verify_no_id(@id)
+      @game.get(params, 'entries/leaderboard')
+    end
+  end
+end

data/lib/strutta-api/errors.rb

@@ -0,0 +1,47 @@
+module Strutta
+  # Strutta Wrapper Errors
+  module Errors
+    # Game ID is required for .get, .update, .delete
+    GAME_ID_REQUIRED = 'Game ID required'
+    # Round ID is required for .get, .update, .delete
+    ROUND_ID_REQUIRED = 'Round ID required'
+    # Participant ID is required for .get, .update, .delete
+    PARTICIPANT_ID_REQUIRED = 'Participant ID required'
+    # Entry ID is required for .get, .update, .delete
+    ENTRY_ID_REQUIRED = 'Entry ID required'
+    # ID is not allowed for some methods
+    OBJECT_NOT_ALLOWED = 'This method may not have an ID associated with it. Example: strutta.games.entries.all instead of strutta.games.entries(ENTRY_ID).all'
+    # ID is not allowed for some methods
+    INVALID_SEARCH = 'This version of the API only support searching by email'
+    # Some http verbs are disabled for object, tell the user nicely
+    METHOD_DISABLED = 'This method is disabled for this object type'
+
+    # Generic Errors
+    class Error < StandardError
+    end
+    # 400 Errors
+    class BadRequestError < Error
+    end
+    # 401 Errors
+    class Unauthorized < Error
+    end
+    # 404 Errors
+    class ObjectNotFoundError < Error
+    end
+    # 422 Errors
+    class UnprocessableEntityError < Error
+    end
+    # .get, .update, .delete requests require an object ID
+    class ObjectIDRequired < Error
+    end
+    # .all, .create do not allow an abject ID
+    class ObjectIDNotAllowed < Error
+    end
+    # Enforce searching only by email
+    class InvalidSearchParameters < Error
+    end
+    # Enforce disabled endpoints
+    class DisabledEndpointError < Error
+    end
+  end
+end

data/lib/strutta-api/flow.rb

@@ -0,0 +1,35 @@
+module Strutta
+  # Flow belongs to a Strutta::Games object
+  # Other Instance methods found in Strutta::APIObject
+  class Flow < APIObject
+    # Initializes the Strutta::Flow object
+    #
+    # @param game [Strutta::Games] Master Strutta::Games object
+    # @return [Strutta::Flow] instantiated Strutta::Flow object
+    def initialize(id = nil, game)
+      @id = id
+      @game = game
+      @root_path = 'flow'
+    end
+
+    # GET request for Flow (no ID required)
+    #
+    # @return [Hash] Parsed body of the API response
+    def get
+      @game.verify_no_id(@id)
+      @game.get({}, @root_path)
+    end
+
+    # DELETE request for Flow (no ID required)
+    #
+    # @return [Hash] Parsed body of the API response
+    def delete
+      @game.verify_no_id(@id)
+      @game.delete(@root_path)
+    end
+
+    # Disbled methods
+    alias_method :update, :method_disabled
+    alias_method :all, :method_disabled
+  end
+end

data/lib/strutta-api/games.rb

@@ -0,0 +1,159 @@
+module Strutta
+  # The Strutta Games object is the master of all other API objects (Rounds, Flow, Entries, Participants)
+  # The above objects are instantiated in association with a Games object, as each belong to a Game in the Strutta API
+  # The above objects also have all their API requests forwarded through this object to Strutta::API
+  class Games
+    attr_accessor :master, :id
+
+    # Initializes the Strutta::Games object
+    #
+    # @param id [Integer, nil] Game id
+    # @param master [Strutta::API] Master Strutta::API object
+    # @return [Strutta::Games] instantiated Strutta::Games object
+    def initialize(id = nil, master)
+      @id = id
+      @root_path = 'games'
+      @master = master
+    end
+
+    # Forwards an API call to @master
+    #
+    # @param method [String] the required HTTP method
+    # @param url [String] URL for the call
+    # @param params [Hash] Parameters for the call
+    # @return [Hash] Parsed body of the response
+    def call(method, url, params = {})
+      @master.call(method, url, params)
+    end
+
+    # Polymorphic GET Index request
+    #
+    # @param resource_path [String, nil] the GET index path for the requesting object
+    #  See Strutta::APIObject#all
+    # @return [Hash] Parsed body of the response
+    def all(params = {}, resource_path = nil)
+      verify_no_id(@id) unless resource_path
+      call('get', "#{@root_path}/#{resource_path}", params)
+    end
+
+    # Polymorphic GET single object request
+    #
+    # @param resource_path [String, nil] the GET path for the requesting object
+    #  See Strutta::APIObject#get
+    # @return [Hash] Parsed body of the response
+    def get(params = {}, resource_path = '')
+      verify_id(@id, Errors::GAME_ID_REQUIRED)
+      call('get', "#{@root_path}/#{@id}/#{resource_path}", params)
+    end
+
+    # Polymorphic POST request
+    #
+    # @param resource_path [String, nil] the POST path for the requesting object
+    #  See Strutta::APIObject#create
+    # @return [Hash] Parsed body of the response
+    def create(params = {}, resource_path = nil)
+      verify_no_id(@id) unless resource_path
+      call('post', "#{@root_path}/#{resource_path}", params)
+    end
+
+    # Polymorphic PATCH request
+    #
+    # @param resource_path [String, nil] the PATCH path for the requesting object
+    #  See Strutta::APIObject#update
+    # @return [Hash] Parsed body of the response
+    def update(params, resource_path = nil)
+      verify_id(@id, Errors::GAME_ID_REQUIRED)
+      call('patch', "#{@root_path}/#{@id}/#{resource_path}", params)
+    end
+
+    # Polymorphic DELETE request
+    #
+    # @param resource_path [String, nil] the DELETE path for the requesting object
+    #  See Strutta::APIObject#delete
+    # @return [Hash] Parsed body of the response
+    def delete(resource_path = nil)
+      verify_id(@id, Errors::GAME_ID_REQUIRED)
+      call('delete', "#{@root_path}/#{@id}/#{resource_path}", {})
+    end
+
+    # Instantiates a Strutta::Rounds object with reference to this Game
+    #
+    # @param id [Integer, nil] the ID of the Round
+    # @return [Strutta::Rounds] The instantiated Strutta::Rounds object
+    def rounds(id = nil)
+      verify_id(@id, Errors::GAME_ID_REQUIRED)
+      Rounds.new id, self
+    end
+
+    # Instantiates a Strutta::Participants object with reference to this Game
+    #
+    # @param id [Integer, nil] the ID of the Participant
+    # @return [Strutta::Participants] The instantiated Strutta::Participants object
+    def participants(id = nil)
+      verify_id(@id, Errors::GAME_ID_REQUIRED)
+      Participants.new id, self
+    end
+
+    # Instantiates a Strutta::Flow object with reference to this Game
+    #
+    # @param id [Integer, nil] Flows do not have Ids. This is here simply for consistency, and will result in error of used.
+    # @return [Strutta::Flow] The instantiated Strutta::Flow object
+    def flow(id = nil)
+      verify_id(@id, Errors::GAME_ID_REQUIRED)
+      Flow.new id, self
+    end
+
+    # Instantiates a Strutta::Entries object with reference to this Game
+    #
+    # @param id [Integer, nil] the ID of the Entry
+    # @return [Strutta::Entries] The instantiated Strutta::Entries object
+    def entries(id = nil)
+      verify_id(@id, Errors::GAME_ID_REQUIRED)
+      Entries.new id, self
+    end
+
+    # Instantiates a Strutta::Points object with reference to this Game
+    #
+    # @param id [Integer, nil] Point IDs are not used by this API. This is here simply for consistency, and will result in error of used.
+    # @return [Strutta::Entries] The instantiated Strutta::Points object
+    def points(id = nil)
+      verify_id(@id, Errors::GAME_ID_REQUIRED)
+      Points.new id, self
+    end
+
+    # Instantiates a Strutta::Moderation object with reference to this Game
+    #
+    # @param id [Integer, nil] Moderation do not have Ids. This is here simply for consistency, and will result in error of used.
+    # @return [Strutta::Entries] The instantiated Strutta::Moderation object
+    def moderation(id = nil)
+      verify_id(@id, Errors::GAME_ID_REQUIRED)
+      Moderation.new id, self
+    end
+
+    # Instantiates a Strutta::Judging object with reference to this Game
+    #
+    # @param id [Integer, nil] Judging does not have Ids. This is here simply for consistency, and will result in error of used.
+    # @return [Strutta::Entries] The instantiated Strutta::Judging object
+    def judging(id = nil)
+      verify_id(@id, Errors::GAME_ID_REQUIRED)
+      Judging.new id, self
+    end
+
+    # Confirm that an id exists for a request
+    #
+    # @param id [Integer] the ID of the objec
+    # @param message [String] Error message if no id exists
+    # @return [nil] nil if id exists, Error otherwise
+    def verify_id(id, message)
+      fail Errors::ObjectIDRequired, message unless id
+    end
+
+    # Confirm that no id exists for a request
+    #
+    # @param id [Integer] the ID of the objec
+    # @return [nil] nil if no id exists, Error otherwise
+    def verify_no_id(id)
+      fail Errors::ObjectIDNotAllowed, Errors::OBJECT_NOT_ALLOWED if id
+    end
+  end
+end