api_bee 0.0.2 → 0.0.3

data/README.mkd

@@ -61,19 +61,33 @@ api.get('/my/resources').each do |r|
 end
 ```
 
+## Delegate to adapter
+
+Lazy-loading and paginating resources is great for GET requests, but you might want to still use your adapter's other methods.
+
+    api = ApiBee.setup(MyCustomAdapter) do |config|
+      config.expose :delete, :post
+    end
+    
+    # This still wraps your adapter's get() method and adds lazy-loading and pagination
+    api.get('/products').first[:title]
+    
+    # This delegates directory to MyCustomAdapter#post()
+    api.post('/products', :title => 'Foo', :price => 100.0)
+
 ## finding a single resource
 
-There's a special find_one method that you can call on lists. It delegates to the adapter and it's useful for finding a single resource in the context of a paginated list.
+There's a special get_one method that you can call on lists. It delegates to the adapter and it's useful for finding a single resource in the context of a paginated list.
 
     resources = api.get('/my/resources')
-    resource = resources.find_one('foobar')
+    resource = resources.get_one('foobar')
     
-That delegates to Adapter#find_one passing 2 arguments: the list's href and the passed name or identifier, so:
+That delegates to Adapter#get_one passing 2 arguments: the list's href and the passed name or identifier, so:
 
 ```ruby
 class ApiBee::Adapters::Special
   # ...
-  def find_one(href, id)
+  def get_one(href, id)
     get "#{href}/#{id}"
   end
 end

data/examples/github_api.rb

@@ -1,14 +1,15 @@
 $LOAD_PATH.unshift '../lib'
 require 'api_bee'
-#require 'net/http'
 require 'net/https'
 require 'uri'
 require 'json'
 
+# Github adapter wraps raw Github API response and decorates collections with
+# pagination parameters needed by APIBee
+#
 class GithubAdapter
   
   def initialize
-    ApiBee.config.uri_property_name = :url
     @url = URI.parse('https://api.github.com')
     @http = Net::HTTP.new(@url.host, @url.port)
     @http.use_ssl = true
@@ -16,8 +17,6 @@ class GithubAdapter
   end
   
   def get(path, options = {})
-    per_page = (options[:per_page] || 20).to_i
-    page = (options[:page] || 1).to_i
     
     q = options.map{|k,v| "#{k}=#{v}"}.join('&')
     
@@ -28,21 +27,9 @@ class GithubAdapter
     
     if response.kind_of?(Net::HTTPOK)
       results = JSON.parse response.body
-      if results.is_a?(Array)
+      results = if results.is_a?(Array)
         # decorate returned array so it complies with APiBee's pagination params
-        results = {
-          :entries => results,
-          :page => page,
-          :per_page => per_page,
-          :url => path
-        }
-        # Extract last page number and entries count. Github uses a 'Link' header
-        if link = response["link"]
-          last_page = extract_last_page(link) || page # if no 'last' link, we're on the last page
-          results.update(
-            :total_entries => last_page.to_i * per_page
-          )
-        end
+        paginate results, options, path, response
       else
         results
       end
@@ -54,12 +41,32 @@ class GithubAdapter
     
   end
   
-  def find_one(href, id)
+  def get_one(href, id)
     get id
   end
   
   protected
   
+  def paginate(results, options, path, response)
+    per_page = (options[:per_page] || 20).to_i
+    page = (options[:page] || 1).to_i
+    
+    results = {
+      :entries => results,
+      :page => page,
+      :per_page => per_page,
+      :url => path
+    }
+    # Extract last page number and entries count. Github uses a 'Link' header
+    if link = response["link"]
+      last_page = extract_last_page(link) || page # if no 'last' link, we're on the last page
+      results.update(
+        :total_entries => last_page.to_i * per_page
+      )
+    end
+    results
+  end
+  
   def extract_last_page(link)
     aa = link.split('<https')
     last_link = aa.find{|e| e=~ /rel="last"/}
@@ -69,12 +76,17 @@ class GithubAdapter
   
 end
 
+########### USAGE ##################################
+
 ## Instantiate your wrapped API
 
-api = ApiBee.setup(GithubAdapter)
+api = ApiBee.setup(GithubAdapter) do |config|
+  config.uri_property_name = :url
+end
 
 repos = api.get('/users/ismasan/repos')
 
+# Recursive method prints results for each page
 def show(data, c)
   puts "+++++++++++++++ Page #{data.current_page} of #{data.total_pages} (#{data.total_entries} entries). #{data.size} now. ++++++++"
   puts
@@ -97,7 +109,7 @@ show repos, 1
 puts "First created at is: #{repos.first[:created_at]}"
 
 # Fetch a single node 
-one = repos.find_one('https://api.github.com/repos/ismasan/websockets_examples')
+one = repos.get_one('https://api.github.com/repos/ismasan/websockets_examples')
 
 # one[:owner][:public_repos] will trigger a new request to the resource URL because that property is not available in the excerpt
 #

data/lib/api_bee/adapters/hash.rb

@@ -25,7 +25,7 @@ module ApiBee
         found
       end
       
-      def find_one(href, id)
+      def get_one(href, id)
         get("#{href}/#{id}")
       end
       
@@ -57,7 +57,7 @@ module ApiBee
       end
       
       def is_paginated?(hash)
-        hash[ApiBee.config.uri_property_name] && hash[:total_entries]
+        hash[:href] && hash[:total_entries]
       end
       
       def paginate(list, page, per_page)

data/lib/api_bee/node.rb

@@ -9,20 +9,21 @@ module ApiBee
       end
     end
     
-    def self.resolve(adapter, attrs, href = nil)
+    def self.resolve(adapter, config, attrs, href = nil)
       attrs = simbolized(attrs)
       keys = attrs.keys.map{|k| k.to_sym}
-      if keys.include?(:total_entries) && keys.include?(ApiBee.config.uri_property_name.to_sym) # is a paginator
-        List.new adapter, attrs, href
+      if keys.include?(config.total_entries_property_name) && keys.include?(config.uri_property_name.to_sym) # is a paginator
+        List.new adapter, config, attrs, href
       else
-        Single.new adapter, attrs, href
+        Single.new adapter, config, attrs, href
       end
     end
     
     attr_reader :adapter
     
-    def initialize(adapter, attrs, href)
+    def initialize(adapter, config, attrs, href)
       @adapter = adapter
+      @config = config
       @attributes = {}
       @href = href
       update_attributes attrs
@@ -54,7 +55,7 @@ module ApiBee
     def resolve_values_to_nodes(value)
       case value
       when ::Hash
-        Node.resolve @adapter, value
+        Node.resolve @adapter, @config, value
       when ::Array
         value.map {|v| resolve_values_to_nodes(v)} # recurse
       else
@@ -63,11 +64,11 @@ module ApiBee
     end
     
     def has_more?
-      !@complete && @attributes[ApiBee.config.uri_property_name]
+      !@complete && @attributes[@config.uri_property_name]
     end
     
     def load_more!
-      more_data = @adapter.get(@attributes[ApiBee.config.uri_property_name])
+      more_data = @adapter.get(@attributes[@config.uri_property_name])
       update_attributes Node.simbolized(more_data) if more_data
       @complete = true
     end
@@ -80,9 +81,9 @@ module ApiBee
       
       DEFAULT_PER_PAGE = 100
       
-      def find_one(id)
-        data = @adapter.find_one(@href, id)
-        data.nil? ? nil : Node.resolve(@adapter, data, @href)
+      def get_one(id)
+        data = @adapter.get_one(@href, id)
+        data.nil? ? nil : Node.resolve(@adapter, @config, data, @href)
       end
       
       def total_entries
@@ -143,14 +144,14 @@ module ApiBee
       end
       
       def paginate(options = {})
-        data = @adapter.get(@attributes[ApiBee.config.uri_property_name], options)
-        Node.resolve @adapter, data, @href
+        data = @adapter.get(@attributes[@config.uri_property_name], options)
+        Node.resolve @adapter, @config, data, @href
       end
       
       protected
       
       def __entries
-        @entries ||= (self[:entries] || [])
+        @entries ||= (self[@config.entries_property_name] || [])
       end
 
     end

data/lib/api_bee/proxy.rb

@@ -4,15 +4,16 @@ module ApiBee
     
     attr_reader :adapter
     
-    def initialize(adapter, href = nil, opts = nil)
+    def initialize(adapter, config, href = nil, opts = nil)
       @adapter = adapter
+      @config = config
       @href = href
       @opts = opts
     end
     
     def get(href, opts = {})
       # Just delegate. No API calls at this point. We only load data when we need it.
-      Proxy.new @adapter, href, opts
+      Proxy.new @adapter, @config, href, opts
     end
     
     def [](key)
@@ -24,20 +25,32 @@ module ApiBee
     end
     
     def paginate(*args)
-      @list ||= Node::List.new(@adapter, {ApiBee.config.uri_property_name => @href}, @href)
+      @list ||= Node::List.new(@adapter, @config, {@config.uri_property_name => @href}, @href)
       @list.paginate *args
     end
     
+    def ==(other)
+      _node.to_data
+    end
+    
     protected
     
     def method_missing(method_name, *args, &block)
-      _node.send(method_name, *args, &block)
+      if _adapter_delegators.include?(method_name)
+        @adapter.send(method_name, *args, &block)
+      else
+        _node.send(method_name, *args, &block)
+      end
+    end
+    
+    def _adapter_delegators
+      @adapter_delegators ||= @config.adapter_delegators || []
     end
     
     def _node
       @node ||= (
         data = @adapter.get(@href, @opts)
-        Node.resolve @adapter, data, @href
+        Node.resolve @adapter, @config, data, @href
       )
     end
     

data/lib/api_bee/version.rb

@@ -1,3 +1,3 @@
 module ApiBee
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/api_bee.rb

@@ -6,8 +6,6 @@ module ApiBee
     
     def setup(adapter_klass, *args)
       
-      yield config if block_given?
-      
       adapter = if adapter_klass.is_a?(::Symbol)
         require File.join('api_bee', 'adapters', adapter_klass.to_s)
         klass = adapter_klass.to_s.gsub(/(^.{1})/){$1.upcase}
@@ -17,18 +15,37 @@ module ApiBee
       end
 
       raise NoMethodError, "Adapter must implement #get(path, *args) method" unless adapter.respond_to?(:get)
-      Proxy.new adapter
+      
+      config = new_config
+      yield config if block_given?
+      Proxy.new adapter, config
+    end
+    
+    # new config object with defaults
+    def new_config
+      Config.new(
+        # This field is expected in API responses
+        # and should point to an individual resource with more data
+        :uri_property_name            => :href,
+        # Total number of entries
+        # Used to paginate lists
+        :total_entries_property_name  => :total_entries,
+        # Name of array property
+        # that contains cureent page's entries
+        :entries_property_name        => :entries
+      )
     end
     
-    def config
-      @config ||= OpenStruct.new
+    class Config < OpenStruct
+      
+      def expose(*fields)
+        self.adapter_delegators = fields
+      end
+      
     end
     
   end
   
-  # Defaults
-  self.config.uri_property_name = :href
-  
   module Adapters
     
   end

data/spec/node_spec.rb

@@ -86,17 +86,18 @@ describe ApiBee do
     
     before do
       @adapter = mock('Adapter')
+      @config = ApiBee.new_config
     end
     
     it 'should resolve single nodes' do
-      node = ApiBee::Node.resolve(@adapter, {:title => 'Blah', :foo => [1,2,3]})
+      node = ApiBee::Node.resolve(@adapter, @config, {:title => 'Blah', :foo => [1,2,3]})
       node[:title].should == 'Blah'
       node.adapter.should == @adapter
       node.should be_kind_of(ApiBee::Node::Single)
     end
     
     it 'should symbolize hash keys' do
-      node = ApiBee::Node.resolve(@adapter, {
+      node = ApiBee::Node.resolve(@adapter, @config, {
         'title' => 'Blah', 
         'total_entries' => 4, 
         'href' => '/products',
@@ -109,7 +110,7 @@ describe ApiBee do
     end
     
     it 'should resolve paginated lists' do
-      node = ApiBee::Node.resolve(@adapter, {:title => 'Blah', :total_entries => 4, :href => '/products'})
+      node = ApiBee::Node.resolve(@adapter, @config, {:title => 'Blah', :total_entries => 4, :href => '/products'})
       node.total_entries.should == 4
       node.adapter.should == @adapter
       node.should be_kind_of(ApiBee::Node::List)
@@ -138,25 +139,25 @@ describe ApiBee do
       end
     end
     
-    describe '#find_one' do
+    describe '#get_one' do
       
       before do
         @products = @api.get('/products', :page => 1, :per_page => 2)
       end
       
       it 'should delegate to adapter. It knows how to find individual resoruces' do
-        @adapter.should_receive(:find_one).with('/products', 'foo-1')
-        @products.find_one('foo-1')
+        @adapter.should_receive(:get_one).with('/products', 'foo-1')
+        @products.get_one('foo-1')
       end
       
       it 'should return a Node::Single' do
-        node = @products.find_one('foo-1')
+        node = @products.get_one('foo-1')
         node.should be_kind_of(ApiBee::Node::Single)
         node[:title].should == 'Foo 1'
       end
       
       it 'should return nil if not found' do
-        @products.find_one('foo-1000').should be_nil
+        @products.get_one('foo-1000').should be_nil
       end
       
     end

data/spec/setup_spec.rb

@@ -10,23 +10,6 @@ describe 'ApiBee.setup' do
     end
   end
   
-  describe 'config block' do
-    
-    it 'should have default uri_property_name field name' do
-      ApiBee.config.uri_property_name.should == :href
-    end
-    
-    it 'should set global variables' do
-      api = ApiBee.setup(:hash, {}) do |config|
-        config.foo = 11
-        config.bar = 22
-      end
-      
-      ApiBee.config.foo.should == 11
-      ApiBee.config.bar.should == 22
-    end
-  end
-  
   describe 'with custom adapter class' do
     before do
       
@@ -57,4 +40,96 @@ describe 'ApiBee.setup' do
     end
     
   end
+  
+  context 'configuration' do
+    
+    before do
+      @api1 = ApiBee.setup(:hash, {
+        :user => {
+          :name => 'ismael 1',
+          :href => '/users/ismael1'
+        }
+      })
+      
+      @api2 = ApiBee.setup(:hash, {
+        :user => {
+          :name => 'ismael 2',
+          :url => '/users/ismael2'
+        }
+      }) do |config|
+        config.uri_property_name = :url
+      end
+    end
+    
+    describe 'API config' do
+      
+      it 'should produce a config object with default values' do
+        config = ApiBee.new_config
+        config.uri_property_name.should == :href
+        config.total_entries_property_name.should == :total_entries
+        config.entries_property_name.should == :entries
+      end
+      
+      it 'should have default :href configured' do
+        user = @api1.get('/user')
+        user[:name].should == 'ismael 1'
+        @api1.adapter.should_receive(:get).with('/users/ismael1').and_return(:last_name => 'Celis')
+
+        user[:last_name].should == 'Celis'
+      end
+      
+      it 'should overwrite config for individual apis' do
+        user1 = @api1.get('/user')
+        user1[:name].should == 'ismael 1'
+        @api1.adapter.should_receive(:get).with('/users/ismael1').and_return(:last_name => 'Celis 1')
+
+        user1[:last_name].should == 'Celis 1'
+        
+        user2 = @api2.get('/user')
+        user2[:name].should == 'ismael 2'
+        @api2.adapter.should_receive(:get).with('/users/ismael2').and_return(:last_name => 'Celis 2')
+
+        user2[:last_name].should == 'Celis 2'
+      end
+
+    end
+    
+    describe 'delegate to adapter' do
+      
+      before do
+        
+        adapter = Class.new(ApiBee::Adapters::Hash) do
+          def fetch(*args)
+            @data.fetch *args
+          end
+          
+          def keys(*args)
+            @data.keys *args
+          end
+        end
+        
+        @api = ApiBee.setup(adapter, {
+          :a => {:name => 1},
+          :b => {:name => 2}
+        }) do |config|
+          config.expose :fetch, :keys
+        end
+        
+      end
+      
+      it 'should still work' do
+        @api.get('/a').should == {:name => 1}
+        @api.get('/b').should == {:name => 2}
+      end
+      
+      it 'should delegate configured methods on to adapter' do
+        @api.fetch(:a).should == {:name => 1}
+        @api.fetch(:x, 'X').should == 'X'
+        
+        @api.keys.should == [:a, :b]
+      end
+      
+    end
+  end
+  
 end

metadata

@@ -2,7 +2,7 @@
 name: api_bee
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors: 
 - Ismael Celis
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-21 00:00:00 Z
+date: 2011-09-22 00:00:00 Z
 dependencies: []
 
 description: API Bee is a small client / spec for a particular style of JSON API. USe Hash adapter for local data access.