thrillcall-api 0.0.3

data/docs/WRAPPER.html

@@ -0,0 +1,182 @@
+
+<style type="text/css">
+.highlight .hll { background-color: #ffffcc }
+.highlight  { background: #dddddd; }
+.highlight .c { color: #408080; font-style: italic } /* Comment */
+.highlight .err { border: 1px solid #FF0000 } /* Error */
+.highlight .k { color: #008000; font-weight: bold } /* Keyword */
+.highlight .o { color: #666666 } /* Operator */
+.highlight .cm { color: #408080; font-style: italic } /* Comment.Multiline */
+.highlight .cp { color: #BC7A00 } /* Comment.Preproc */
+.highlight .c1 { color: #408080; font-style: italic } /* Comment.Single */
+.highlight .cs { color: #408080; font-style: italic } /* Comment.Special */
+.highlight .gd { color: #A00000 } /* Generic.Deleted */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gr { color: #FF0000 } /* Generic.Error */
+.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.highlight .gi { color: #00A000 } /* Generic.Inserted */
+.highlight .go { color: #808080 } /* Generic.Output */
+.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.highlight .gt { color: #0040D0 } /* Generic.Traceback */
+.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
+.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
+.highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
+.highlight .kp { color: #008000 } /* Keyword.Pseudo */
+.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
+.highlight .kt { color: #B00040 } /* Keyword.Type */
+.highlight .m { color: #666666 } /* Literal.Number */
+.highlight .s { color: #BA2121 } /* Literal.String */
+.highlight .na { color: #7D9029 } /* Name.Attribute */
+.highlight .nb { color: #008000 } /* Name.Builtin */
+.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */
+.highlight .no { color: #880000 } /* Name.Constant */
+.highlight .nd { color: #AA22FF } /* Name.Decorator */
+.highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */
+.highlight .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
+.highlight .nf { color: #0000FF } /* Name.Function */
+.highlight .nl { color: #A0A000 } /* Name.Label */
+.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
+.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
+.highlight .nv { color: #19177C } /* Name.Variable */
+.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
+.highlight .w { color: #bbbbbb } /* Text.Whitespace */
+.highlight .mf { color: #666666 } /* Literal.Number.Float */
+.highlight .mh { color: #666666 } /* Literal.Number.Hex */
+.highlight .mi { color: #666666 } /* Literal.Number.Integer */
+.highlight .mo { color: #666666 } /* Literal.Number.Oct */
+.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
+.highlight .sc { color: #BA2121 } /* Literal.String.Char */
+.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
+.highlight .s2 { color: #BA2121 } /* Literal.String.Double */
+.highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
+.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
+.highlight .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
+.highlight .sx { color: #008000 } /* Literal.String.Other */
+.highlight .sr { color: #BB6688 } /* Literal.String.Regex */
+.highlight .s1 { color: #BA2121 } /* Literal.String.Single */
+.highlight .ss { color: #19177C } /* Literal.String.Symbol */
+.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
+.highlight .vc { color: #19177C } /* Name.Variable.Class */
+.highlight .vg { color: #19177C } /* Name.Variable.Global */
+.highlight .vi { color: #19177C } /* Name.Variable.Instance */
+.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */
+</style><h1>Thrillcall API</h1>
+
+<p>This document describes the Thrillcall API v2, and usage for the provided Ruby API wrapper gem.</p>
+
+<h1>Ruby API Wrapper</h1>
+
+<h3>Usage:</h3>
+
+<div class="highlight">
+<pre>    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="c1"># First, require the gem:</span>
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="nb">require</span> <span class="s1">'rubygems'</span>
+    <span class="nb">require</span> <span class="s1">'thrillcall-api'</span>
+
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="c1"># Instantiate with your Thrillcall API key:</span>
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="no">MY_API_KEY</span> <span class="o">=</span> <span class="s2">"1234567890abcdef"</span>
+    <span class="n">tc</span> <span class="o">=</span> <span class="no">ThrillcallAPI</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="no">MY_API_KEY</span><span class="p">)</span>
+
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="c1"># Access any endpoint directly from the instance</span>
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="c1"># This is like calling GET "/events"</span>
+    <span class="n">tc</span><span class="o">.</span><span class="n">events</span>
+    <span class="c1"># =&gt; [ {"id" =&gt; ... }, {...}, ...]</span>
+
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="c1"># Provide IDs as arguments</span>
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="c1"># GET "/event/1"</span>
+    <span class="n">tc</span><span class="o">.</span><span class="n">event</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
+    <span class="c1"># =&gt; {"id" =&gt; 1, ...}</span>
+
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="c1"># Provide parameters as arguments</span>
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="c1"># GET "/events?limit=5"</span>
+    <span class="n">events</span> <span class="o">=</span> <span class="n">tc</span><span class="o">.</span><span class="n">events</span><span class="p">(</span><span class="ss">:limit</span> <span class="o">=&gt;</span> <span class="mi">5</span><span class="p">)</span>
+    <span class="c1"># =&gt; [ {"id" =&gt; ... }, {...}, ...]</span>
+    <span class="n">events</span><span class="o">.</span><span class="n">length</span>
+    <span class="c1"># =&gt; 5</span>
+
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="c1"># Chain methods together for nested routes</span>
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="c1"># GET "/search/venues/warfield?postalcode=94101&amp;radius=20"</span>
+    <span class="n">venues</span> <span class="o">=</span> <span class="n">tc</span><span class="o">.</span><span class="n">search</span><span class="o">.</span><span class="n">venues</span><span class="p">(</span><span class="s2">"warfield"</span><span class="p">,</span> <span class="ss">:postalcode</span> <span class="o">=&gt;</span> <span class="s2">"94101"</span><span class="p">,</span> <span class="ss">:radius</span> <span class="o">=&gt;</span> <span class="mi">20</span><span class="p">)</span>
+    <span class="c1"># =&gt; [{"name" =&gt; "The Warfield", ...}]</span>
+</pre>
+</div>
+
+
+<h3>Advanced Usage:</h3>
+
+<p>Provide additional instantiation options:</p>
+
+<div class="highlight">
+<pre>    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="c1"># The default SSL endpoint is "https://api.thrillcall.com/api/".</span>
+    <span class="c1"># The default API version is 2.</span>
+    <span class="c1"># By default, Faraday access logging is turned off.</span>
+    <span class="c1"># Override if necessary:</span>
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="n">tc</span> <span class="o">=</span> <span class="no">ThrillcallAPI</span><span class="o">.</span><span class="n">new</span><span class="p">(</span>
+      <span class="no">MY_API_KEY</span><span class="p">,</span>
+      <span class="ss">:base_url</span> <span class="o">=&gt;</span> <span class="s2">"https://api.thrillcall.com/custom/"</span><span class="p">,</span>
+      <span class="ss">:version</span>  <span class="o">=&gt;</span> <span class="mi">3</span><span class="p">,</span>
+      <span class="ss">:logger</span>   <span class="o">=&gt;</span> <span class="kp">true</span>
+    <span class="p">)</span>
+</pre>
+</div>
+
+
+<p>Internally, the wrapper returns a ThrillcallAPI::Result class for any call.  Data for the request is fetched only when used.  This allows you to build requests piecemeal before executing them.</p>
+
+<div class="highlight">
+<pre>    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="c1"># Build a partial request, add on to it later</span>
+    <span class="c1">#---------------------------------------------------------------#</span>
+    <span class="n">request</span> <span class="o">=</span> <span class="n">tc</span><span class="o">.</span><span class="n">artist</span><span class="p">(</span><span class="mi">22210</span><span class="p">)</span> <span class="c1"># Lady Gaga</span>
+
+    <span class="c1"># GET "/artist/22210/events?limit=2"</span>
+    <span class="n">artist_events</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">events</span><span class="p">(</span><span class="ss">:limit</span> <span class="o">=&gt;</span> <span class="mi">2</span><span class="p">)</span>
+
+    <span class="n">artist_events</span><span class="o">.</span><span class="n">length</span>
+    <span class="c1"># =&gt; 2</span>
+</pre>
+</div>
+
+
+<p>This gem is a convenience wrapper around the excellent Faraday project.  If more complicated use cases are necessary, consider using Faraday directly.</p>
+
+<div class="highlight">
+<pre>    <span class="nb">require</span> <span class="s1">'faraday'</span>
+    <span class="nb">require</span> <span class="s1">'json'</span>
+
+    <span class="no">MY_API_KEY</span>  <span class="o">=</span> <span class="s2">"1234567890abcdef"</span>
+    <span class="no">BASE_URL</span>    <span class="o">=</span> <span class="s2">"https://api.thrillcall.com/api/v2/"</span>
+    <span class="no">HEADERS</span>     <span class="o">=</span> <span class="p">{</span> <span class="ss">:accept</span> <span class="o">=&gt;</span> <span class="s1">'application/json'</span> <span class="p">}</span>
+
+    <span class="n">connection</span>  <span class="o">=</span> <span class="no">Faraday</span><span class="o">.</span><span class="n">new</span><span class="p">(</span> <span class="ss">:url</span> <span class="o">=&gt;</span> <span class="no">BASE_URL</span><span class="p">,</span> <span class="ss">:headers</span> <span class="o">=&gt;</span> <span class="no">HEADERS</span> <span class="p">)</span> <span class="k">do</span> <span class="o">|</span><span class="n">builder</span><span class="o">|</span>
+      <span class="n">builder</span><span class="o">.</span><span class="n">adapter</span> <span class="no">Faraday</span><span class="o">.</span><span class="n">default_adapter</span>
+      <span class="n">builder</span><span class="o">.</span><span class="n">response</span> <span class="ss">:logger</span>
+      <span class="n">builder</span><span class="o">.</span><span class="n">response</span> <span class="ss">:raise_error</span>
+    <span class="k">end</span>
+
+    <span class="n">request</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">get</span> <span class="k">do</span> <span class="o">|</span><span class="n">req</span><span class="o">|</span>
+      <span class="n">req</span><span class="o">.</span><span class="n">url</span> <span class="s2">"artist/22210"</span><span class="p">,</span> <span class="p">{</span> <span class="ss">:api_key</span> <span class="o">=&gt;</span> <span class="no">MY_API_KEY</span> <span class="p">}</span>
+    <span class="k">end</span>
+
+    <span class="n">artist</span> <span class="o">=</span> <span class="no">JSON</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">body</span><span class="p">)</span>
+
+    <span class="n">artist</span><span class="o">[</span><span class="s2">"name"</span><span class="o">]</span>
+    <span class="c1"># =&gt; "Lady Gaga"</span>
+</pre>
+</div>

data/docs/WRAPPER.md

@@ -0,0 +1,115 @@
+# Thrillcall API
+This document describes the Thrillcall API v2, and usage for the provided Ruby API wrapper gem.
+
+# Ruby API Wrapper
+### Usage:
+
+``` ruby
+    #---------------------------------------------------------------#
+    # First, require the gem:
+    #---------------------------------------------------------------#
+    require 'rubygems'
+    require 'thrillcall-api'
+    
+    #---------------------------------------------------------------#
+    # Instantiate with your Thrillcall API key:
+    #---------------------------------------------------------------#
+    MY_API_KEY = "1234567890abcdef"
+    tc = ThrillcallAPI.new(MY_API_KEY)
+    
+    #---------------------------------------------------------------#
+    # Access any endpoint directly from the instance
+    #---------------------------------------------------------------#
+    # This is like calling GET "/events"
+    tc.events
+    # => [ {"id" => ... }, {...}, ...]
+    
+    #---------------------------------------------------------------#
+    # Provide IDs as arguments
+    #---------------------------------------------------------------#
+    # GET "/event/1"
+    tc.event(1)
+    # => {"id" => 1, ...}
+    
+    #---------------------------------------------------------------#
+    # Provide parameters as arguments
+    #---------------------------------------------------------------#
+    # GET "/events?limit=5"
+    events = tc.events(:limit => 5)
+    # => [ {"id" => ... }, {...}, ...]
+    events.length
+    # => 5
+    
+    #---------------------------------------------------------------#
+    # Chain methods together for nested routes
+    #---------------------------------------------------------------#
+    # GET "/search/venues/warfield?postalcode=94101&radius=20"
+    venues = tc.search.venues("warfield", :postalcode => "94101", :radius => 20)
+    # => [{"name" => "The Warfield", ...}]
+```
+
+### Advanced Usage:
+
+Provide additional instantiation options:
+
+``` ruby
+    
+    #---------------------------------------------------------------#
+    # The default SSL endpoint is "https://api.thrillcall.com/api/".
+    # The default API version is 2.
+    # By default, Faraday access logging is turned off.
+    # Override if necessary:
+    #---------------------------------------------------------------#
+    tc = ThrillcallAPI.new(
+      MY_API_KEY,
+      :base_url => "https://api.thrillcall.com/custom/",
+      :version  => 3,
+      :logger   => true
+    )
+    
+```
+
+Internally, the wrapper returns a ThrillcallAPI::Result class for any call.  Data for the request is fetched only when used.  This allows you to build requests piecemeal before executing them.
+
+``` ruby
+    
+    #---------------------------------------------------------------#
+    # Build a partial request, add on to it later
+    #---------------------------------------------------------------#
+    request = tc.artist(22210) # Lady Gaga
+    
+    # GET "/artist/22210/events?limit=2"
+    artist_events = request.events(:limit => 2)
+    
+    artist_events.length
+    # => 2
+    
+```
+
+This gem is a convenience wrapper around the excellent Faraday project.  If more complicated use cases are necessary, consider using Faraday directly.
+
+``` ruby
+    
+    require 'faraday'
+    require 'json'
+    
+    MY_API_KEY  = "1234567890abcdef"
+    BASE_URL    = "https://api.thrillcall.com/api/v2/"
+    HEADERS     = { :accept => 'application/json' }
+    
+    connection  = Faraday.new( :url => BASE_URL, :headers => HEADERS ) do |builder|
+      builder.adapter Faraday.default_adapter
+      builder.response :logger
+      builder.response :raise_error
+    end
+    
+    request = connection.get do |req|
+      req.url "artist/22210", { :api_key => MY_API_KEY }
+    end
+    
+    artist = JSON.parse(request.body)
+    
+    artist["name"]
+    # => "Lady Gaga"
+    
+```

data/lib/thrillcall-api.rb

@@ -0,0 +1,76 @@
+require 'faraday'
+require 'json'
+require "#{File.expand_path("../thrillcall-api/exceptions", __FILE__)}"
+require "#{File.expand_path("../thrillcall-api/result", __FILE__)}"
+require "#{File.expand_path("../thrillcall-api/version", __FILE__)}"
+
+module ThrillcallAPI
+  class << self
+    attr_accessor :cur_api_key, :base, :result, :conn
+
+    # Set up the Faraday connection based on configuration
+    def new(cur_api_key, options = {})
+      default_options = {
+        :base_url   => "https://api.thrillcall.com/api/",
+        :version    => 2,
+        :logger     => false
+      }
+
+      opts = default_options.merge(options)
+
+      @cur_api_key  = cur_api_key
+      base_url      = opts[:base_url]
+      version       = opts[:version]
+      logger        = opts[:logger]
+
+      # Make sure the base_url is in the form https://.../
+      unless base_url.match /^(http|https):\/\//
+        base_url = "https://" + base_url
+      end
+
+      unless base_url.match /\/$/
+        base_url = base_url + "/"
+      end
+
+      # Set JSON accept header and custom user agent
+      @headers = {
+        :accept     => 'application/json',
+        :user_agent => "Thrillcall API Wrapper version #{ThrillcallAPI::VERSION}"
+      }
+
+      @base   = "#{base_url}v#{version}/"
+      @conn   = Faraday.new( :url => @base, :headers => @headers ) do |builder|
+        builder.adapter Faraday.default_adapter
+        if logger
+          builder.response :logger
+        end
+        # This will raise an exception if an error occurs during a request
+        builder.response :raise_error
+      end
+
+      @result = Result.new
+
+      return self
+    end
+
+    def get(endpoint, params)
+      r = @conn.get do |req|
+        req.url endpoint, params.merge(:api_key => @cur_api_key)
+      end
+      JSON.parse(r.body)
+    end
+
+    def post(endpoint, params)
+      r = @conn.post do |req|
+        req.url endpoint, params.merge(:api_key => @cur_api_key)
+      end
+      JSON.parse(r.body)
+    end
+
+    def method_missing(method, *args, &block)
+      r = Result.new
+      r.send(method, args, block)
+      return r
+    end
+  end
+end

data/lib/thrillcall-api/exceptions.rb

@@ -0,0 +1,7 @@
+module ThrillcallAPI
+  class Error < StandardError
+    def initialize(details = {})
+      super("#{details[:type]}: #{details[:message]}")
+    end
+  end
+end

data/lib/thrillcall-api/result.rb

@@ -0,0 +1,142 @@
+# Adapted from
+# http://stackoverflow.com/questions/1332404/how-to-detect-the-end-of-a-method-chain-in-ruby
+# and
+# http://blog.jayfields.com/2008/02/ruby-replace-methodmissing-with-dynamic.html
+
+module ThrillcallAPI
+  class Result
+    attr_accessor :ran, :request_keys, :options, :set_methods, :http_method
+    attr_reader :data
+    
+    def initialize
+      reset
+    end
+    
+    def reset
+      if @set_methods
+        unset_methods
+      end
+      @ran                      = false
+      @data                     = {} # could be an array after fetch
+      @end_of_chain_is_singular = false
+      @options                  = {}
+      @request_keys             = []
+      @set_methods              = []
+      @http_method              = :get
+    end
+    
+    # Removes any dynamically defined methods
+    def unset_methods
+      @set_methods.each do |s|
+        (class << self; self; end).class_eval do
+          undef_method s
+        end
+      end
+      
+      @set_methods = []
+    end
+    
+    # Dynamically defines any methods available to data.
+    # i.e. it puts on a "#{data.class}" costume
+    def reassign(data)
+      unset_methods
+      
+      data.public_methods(false).each do |meth|
+        @set_methods << meth
+        (class << self; self; end).class_eval do
+          define_method meth do |*args, &block|
+            data.send meth, *args, &block
+          end
+        end
+      end
+    end
+    
+    # Append the name of the method and any args to the current
+    # request being built
+    def append(key, *args)
+      
+      # If this is called but we've already fetched data, reset
+      if @ran
+        reset
+      end
+      
+      @request_keys << key
+      
+      if args
+        if args.is_a? Array
+          args = args.flatten
+        end
+        args.each do |arg|
+          if arg
+            a = arg
+            if a.is_a? Hash
+              # Merge this hash on top of the existing options
+              @options.merge!(a)
+            else
+              # This is an ID or search term, add it directly to the
+              # list of keys
+              @request_keys << a.to_s
+            end
+          end
+        end
+      end
+    end
+    
+    def run(method, *args, &block)
+      # Fetch data if necessary.  This will also "put on the
+      # data.class costume" and allow the method to respond to a
+      # subsequent send()
+      if !@ran
+        fetch_data
+      end
+      
+      # Send the requested method out to the newly defined method
+      self.send(method, *args, &block)
+    end
+    
+    def fetch_data
+      url = URI.escape(@request_keys.join("/"))
+      
+      @data = ThrillcallAPI.send(@http_method, url, @options)
+      
+      # Now we define the instance methods present in the data object
+      # so that we can use this object *as if* we are using the data
+      # object directly and we don't encounter method_missing
+      reassign(@data)
+      
+      @ran = true
+    end
+    
+    def post(args = {})
+      if @ran
+        raise ArgumentError, "This request has already been made!"
+      else
+        @http_method = :post
+        @options.merge!(args)
+        fetch_data
+      end
+      @data
+    end
+    
+    def method_missing(method, *args, &block)
+      
+      if @ran
+        # NoMethodError
+        super
+      else
+        # We haven't fetched the data yet, but if this method is for
+        # a hash or an array, we'd better.
+        # The bad news about this technique is that we can't have any
+        # endpoints that map to array or hash methods
+        if {}.respond_to?(method) || [].respond_to?(method)
+          r = run(method, *args, &block)
+          return r
+        else # Keep building the request
+          append(method, *args)
+          return self
+        end
+      end
+    end
+    
+  end
+end