api_bee 0.0.1 → 0.0.2

data/README.mkd

@@ -61,6 +61,24 @@ api.get('/my/resources').each do |r|
 end
 ```
 
+## 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.
+
+    resources = api.get('/my/resources')
+    resource = resources.find_one('foobar')
+    
+That delegates to Adapter#find_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)
+    get "#{href}/#{id}"
+  end
+end
+```
+
 ## Lazy loading
 
 ApiBee wraps your adapters in lazy-loading objects. API calls will only be issued when accessing or iterating data.
@@ -117,3 +135,7 @@ products.has_prev_page? # => true
     
 products.prev_page # => 1
 ``` 
+
+## Examples
+
+See examples/github_api.rb for an adapter that paginates Github's API by decorating it's results with ApiBee's required pagination properties

data/examples/github_api.rb

@@ -0,0 +1,104 @@
+$LOAD_PATH.unshift '../lib'
+require 'api_bee'
+#require 'net/http'
+require 'net/https'
+require 'uri'
+require 'json'
+
+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
+    @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+  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('&')
+    
+    fullpath = "#{path}?#{q}"
+    
+    request = Net::HTTP::Get.new(fullpath)
+    response = @http.request(request)
+    
+    if response.kind_of?(Net::HTTPOK)
+      results = JSON.parse response.body
+      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
+      else
+        results
+      end
+      
+      results
+    else
+      nil
+    end
+    
+  end
+  
+  def find_one(href, id)
+    get id
+  end
+  
+  protected
+  
+  def extract_last_page(link)
+    aa = link.split('<https')
+    last_link = aa.find{|e| e=~ /rel="last"/}
+    last_link.to_s =~ /\?page=(\d+)/
+    $1
+  end
+  
+end
+
+## Instantiate your wrapped API
+
+api = ApiBee.setup(GithubAdapter)
+
+repos = api.get('/users/ismasan/repos')
+
+def show(data, c)
+  puts "+++++++++++++++ Page #{data.current_page} of #{data.total_pages} (#{data.total_entries} entries). #{data.size} now. ++++++++"
+  puts
+  data.each do |pp|
+    puts "#{c}.- #{pp[:id]}: #{pp[:name]}. Forks: #{pp[:forks]}. URL: #{pp[:url]}"
+    c += 1
+  end
+  puts
+  p [:next, data.next_page, data.total_entries]
+  if data.has_next_page? # recurse
+    show data.paginate(:page => data.next_page, :per_page => 20), c
+  end
+end
+
+## Auto paginate over all the repos
+
+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[:owner][:public_repos] will trigger a new request to the resource URL because that property is not available in the excerpt
+#
+puts "An owner is #{one[:owner][:login]}, who has #{one[:owner][:public_repos]} public repos"

data/examples/yaml_catalog.rb

@@ -4,9 +4,17 @@ require 'api_bee'
 
 api = ApiBee.setup(:hash, YAML.load_file('./catalog.yml'))
 
+collections = api.get('/collections')
+
+#p collections
+
+p collections.current_page
+# p collections.size
+
 collection = api.get('/collections/c1')
 
 p collection[:title]
+p collection[:id]
 
 products = collection[:products]
 

data/lib/api_bee/adapters/hash.rb

@@ -25,6 +25,10 @@ module ApiBee
         found
       end
       
+      def find_one(href, id)
+        get("#{href}/#{id}")
+      end
+      
       protected
       
       def parse_href(href)
@@ -60,7 +64,7 @@ module ApiBee
         from = page * per_page - per_page
         to =  page * per_page
         list[:entries] = list[:entries].to_a[from...to]
-        list[:current_page] = page
+        list[:page] = page
         list[:per_page] = per_page
         list
       end

data/lib/api_bee/node.rb

@@ -2,25 +2,40 @@ module ApiBee
   
   class Node
     
-    def self.resolve(adapter, attrs)
+    def self.simbolized(hash)
+      hash.inject({}) do |options, (key, value)|
+        options[(key.to_sym rescue key) || key] = value
+        options
+      end
+    end
+    
+    def self.resolve(adapter, 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) # is a paginator
-        List.new adapter, attrs
+      if keys.include?(:total_entries) && keys.include?(ApiBee.config.uri_property_name.to_sym) # is a paginator
+        List.new adapter, attrs, href
       else
-        Single.new adapter, attrs
+        Single.new adapter, attrs, href
       end
     end
     
     attr_reader :adapter
     
-    def initialize(adapter, attrs)
+    def initialize(adapter, attrs, href)
       @adapter = adapter
       @attributes = {}
+      @href = href
       update_attributes attrs
     end
     
+    def to_data
+      @attributes
+    end
+    
     def [](attribute_name)
-      if value = @attributes[attribute_name]
+      if respond_to?(attribute_name)
+        send attribute_name
+      elsif value = @attributes[attribute_name]
         resolve_values_to_nodes value
       elsif has_more? # check whether there's more info in API
         load_more!
@@ -53,7 +68,7 @@ module ApiBee
     
     def load_more!
       more_data = @adapter.get(@attributes[ApiBee.config.uri_property_name])
-      update_attributes more_data if more_data
+      update_attributes Node.simbolized(more_data) if more_data
       @complete = true
     end
     
@@ -65,16 +80,21 @@ module ApiBee
       
       DEFAULT_PER_PAGE = 100
       
+      def find_one(id)
+        data = @adapter.find_one(@href, id)
+        data.nil? ? nil : Node.resolve(@adapter, data, @href)
+      end
+      
       def total_entries
         @attributes[:total_entries].to_i
       end
       
       def size
-        entries.size
+        __entries.size
       end
       
       def current_page
-        (@attributes[:current_page] || 1).to_i
+        (@attributes[:page] || 1).to_i
       end
       
       def per_page
@@ -82,7 +102,7 @@ module ApiBee
       end
       
       def total_pages
-        div = total_entries / per_page
+        div = (total_entries.to_f / per_page.to_f).ceil
         div < 1 ? 1 : div
       end
       
@@ -107,29 +127,29 @@ module ApiBee
       end
       
       def first
-        entries.first
+        __entries.first
       end
       
       def last
-        entries.last
+        __entries.last
       end
       
       def each(&block)
-        entries.each(&block)
+        __entries.each(&block)
       end
       
       def each_with_index(&block)
-        entries.each_with_index(&block)
+        __entries.each_with_index(&block)
       end
       
       def paginate(options = {})
         data = @adapter.get(@attributes[ApiBee.config.uri_property_name], options)
-        Node.resolve @adapter, data
+        Node.resolve @adapter, data, @href
       end
       
       protected
       
-      def entries
+      def __entries
         @entries ||= (self[:entries] || [])
       end
 

data/lib/api_bee/proxy.rb

@@ -4,12 +4,41 @@ module ApiBee
     
     attr_reader :adapter
     
-    def initialize(adapter)
+    def initialize(adapter, href = nil, opts = nil)
       @adapter = adapter
+      @href = href
+      @opts = opts
     end
     
-    def get(href)
-      Node.resolve @adapter, ApiBee.config.uri_property_name => href
+    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
+    end
+    
+    def [](key)
+      _node[key]
+    end
+    
+    def to_data
+      _node.to_data
+    end
+    
+    def paginate(*args)
+      @list ||= Node::List.new(@adapter, {ApiBee.config.uri_property_name => @href}, @href)
+      @list.paginate *args
+    end
+    
+    protected
+    
+    def method_missing(method_name, *args, &block)
+      _node.send(method_name, *args, &block)
+    end
+    
+    def _node
+      @node ||= (
+        data = @adapter.get(@href, @opts)
+        Node.resolve @adapter, data, @href
+      )
     end
     
   end

data/lib/api_bee/version.rb

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

data/spec/hash_adapter_spec.rb

@@ -12,8 +12,8 @@ describe ApiBee::Adapters::Hash do
           :id             => 'catalog',
           :foos           => [1,2,3,4],
           :products       => {
-            :total_entries    => 4,
-            :current_page     => 1,
+            :total_entries    => 5,
+            :page     => 1,
             :per_page         => 4,
             :href             => '/collections/catalog/products',
             :entries            => [
@@ -35,7 +35,12 @@ describe ApiBee::Adapters::Hash do
                 :id           => 'foo-4',
                 :title        => 'Foo 4',
                 :href         => '/products/foo-4'
-              }
+              },
+               {
+                 :id           => 'foo-5',
+                 :title        => 'Foo 5',
+                 :href         => '/products/foo-5'
+               }
             ]
           }
         }
@@ -45,6 +50,12 @@ describe ApiBee::Adapters::Hash do
     @adapter        = ApiBee::Adapters::Hash.new(@data)
   end
   
+  context 'non-existing data' do
+    it 'should return nil' do
+      @adapter.get('/foo/lolz').should be_nil
+    end
+  end
+  
   context 'accessing single nodes' do
     
     before do
@@ -64,20 +75,31 @@ describe ApiBee::Adapters::Hash do
     it 'should return whole collection if no pagination' do
       products = @adapter.get('/collections/catalog/products')
       # products.should == 1
-      products[:current_page].should == 1
-      products[:total_entries].should == 4
+      products[:page].should == 1
+      products[:total_entries].should == 5
       products[:per_page].should == 4
-      products[:entries].size.should == 4
+      products[:entries].size.should == 5
     end
     
-    it 'should paginate paginated collections' do
-      products = @adapter.get('/collections/catalog/products', :page => 2, :per_page => 2)
-      products[:current_page].should == 2
-      products[:total_entries].should == 4
-      products[:per_page].should == 2
-      products[:entries].size.should == 2
-      products[:entries][0][:title].should == 'Foo 3'
-      products[:entries][1][:title].should == 'Foo 4'
+    describe 'paginating' do
+      it 'should paginate paginated collections' do
+        products = @adapter.get('/collections/catalog/products', :page => 2, :per_page => 2)
+        products[:page].should == 2
+        products[:total_entries].should == 5
+        products[:per_page].should == 2
+        products[:entries].size.should == 2
+        products[:entries][0][:title].should == 'Foo 3'
+        products[:entries][1][:title].should == 'Foo 4'
+      end
+      
+      it 'should paginate last page correctly' do
+        products = @adapter.get('/collections/catalog/products', :page => 3, :per_page => 2)
+        products[:page].should == 3
+        products[:total_entries].should == 5
+        products[:per_page].should == 2
+        products[:entries].size.should == 1
+        products[:entries][0][:title].should == 'Foo 5'
+      end
     end
   end
   

data/spec/node_spec.rb

@@ -7,7 +7,7 @@ describe ApiBee do
       # Products
       :products         => {
         :href => '/products',
-        :total_entries => 6,
+        :total_entries => 7,
         :entries => [
           {
             :title        => 'Foo 1',
@@ -44,6 +44,12 @@ describe ApiBee do
             :id           => 'foo-6',
             :price        => 600,
             :description  => 'Foo 6 desc'
+          },
+          {
+            :title        => 'Foo 7',
+            :id           => 'foo-7',
+            :price        => 700,
+            :description  => 'Foo 7 desc'
           }
         ]
       },
@@ -55,7 +61,7 @@ describe ApiBee do
           :products       => {
             :href           => '/products',
             :total_entries    => 4,
-            :current_page     => 1,
+            :page             => 1,
             :per_page         => 2,
             :href             => '/products',
             :entries            => [
@@ -89,6 +95,19 @@ describe ApiBee do
       node.should be_kind_of(ApiBee::Node::Single)
     end
     
+    it 'should symbolize hash keys' do
+      node = ApiBee::Node.resolve(@adapter, {
+        'title' => 'Blah', 
+        'total_entries' => 4, 
+        'href' => '/products',
+        'foos' => [1,2,3,4]
+      })
+      node.total_entries.should == 4
+      node[:foos].should == [1,2,3,4]
+      node.adapter.should == @adapter
+      node.should be_kind_of(ApiBee::Node::List)
+    end
+    
     it 'should resolve paginated lists' do
       node = ApiBee::Node.resolve(@adapter, {:title => 'Blah', :total_entries => 4, :href => '/products'})
       node.total_entries.should == 4
@@ -112,14 +131,83 @@ describe ApiBee do
     describe 'single nodes' do
       it 'should call adapter only when accessing needed attributes' do
         hash = @data[:collections].last
-        @adapter.should_receive(:get).exactly(1).times.with('/collections/catalog').and_return hash
+        @adapter.should_receive(:get).exactly(1).times.with('/collections/catalog', {}).and_return hash
         node = @api.get('/collections/catalog')
         node[:title].should == 'Catalog'
         node[:id].should == 'catalog'
       end
     end
     
-    describe 'paginated lists' do
+    describe '#find_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')
+      end
+      
+      it 'should return a Node::Single' do
+        node = @products.find_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
+      end
+      
+    end
+    
+  end
+  
+  context 'navigating data' do
+    
+    before do
+      @api = ApiBee.setup(:hash, @data)
+    end
+    
+    describe '#to_data' do
+      it 'should return raw data' do
+        d = @api.get('/collections/catalog').to_data
+        d.should be_kind_of(::Hash)
+        d.should == @data[:collections].first
+      end
+    end
+    
+    describe 'paginated root level lists' do
+      
+      before do
+        @products = @api.get('/products', :page => 1, :per_page => 2)
+      end
+      
+      it 'should have a paginator interface' do
+        
+        @products.total_entries.should == 7
+        @products.size.should == 2
+        @products.total_pages.should == 4
+        @products.current_page.should == 1
+        @products.pages.should == [1,2,3,4]
+        @products.has_next_page?.should be_true
+        @products.has_prev_page?.should be_false
+      end
+      
+      it 'should paginate last page correctly' do
+        last_page = @products.paginate(:per_page => 2, :page =>4)
+
+        last_page.total_entries.should == 7
+        last_page.size.should == 1
+        last_page.total_pages.should == 4
+        last_page.current_page.should == 4
+        last_page.pages.should == [1,2,3,4]
+        last_page.has_next_page?.should be_false
+        last_page.has_prev_page?.should be_true
+      end
+    end
+    
+    describe 'paginated nested lists' do
       before do
         @collection = @api.get('/collections/catalog')
         @products = @collection[:products]
@@ -153,7 +241,7 @@ describe ApiBee do
         @products.each {|p| titles << p[:title]}
         @products.each {|p| klasses << p.class}
         @products.current_page.should == 2
-        @products.total_entries.should == 6
+        @products.total_entries.should == 7
         @products.size.should == 2
         klasses.should == [ApiBee::Node::Single, ApiBee::Node::Single]
         titles.should == ['Foo 3', 'Foo 4']

metadata

@@ -2,7 +2,7 @@
 name: api_bee
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Ismael Celis
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-19 00:00:00 Z
+date: 2011-09-21 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.
@@ -30,6 +30,7 @@ files:
 - Rakefile
 - api_bee.gemspec
 - examples/catalog.yml
+- examples/github_api.rb
 - examples/yaml_catalog.rb
 - lib/api_bee.rb
 - lib/api_bee/adapters/hash.rb