api_bee 0.0.3 → 0.0.4

data/README.mkd

@@ -51,85 +51,153 @@ class ApiBee::Adapters::Special
 end
 ```
 
-The use it:
+ApiBee wraps your adapter and makes results lazily-loaded. That is, actual requests won't be made until accessing attributes or iterating the data set.
+
+Use it:
 
 ```ruby
 api = ApiBee.setup :special, optional_custom_data
 
-api.get('/my/resources').each do |r|
+# No actual request made
+resources = api.get('/my/resources')
+
+# Requests once under the hood so you can iterate
+resources.each do |r|
   r[:name]
 end
 ```
 
-## Delegate to adapter
+## Lazy-loading
 
-Lazy-loading and paginating resources is great for GET requests, but you might want to still use your adapter's other methods.
+If an object in a response has a 'href' attribute, it will be used to fetch more data if you ask for an attribute currently not in the object.
 
-    api = ApiBee.setup(MyCustomAdapter) do |config|
-      config.expose :delete, :post
-    end
+    # JSON Dataset
+    {
+      'user': {
+        'name': 'Ismael',
+        'href': 'http://api.com/users/ismael'
+      }
+    }
     
-    # This still wraps your adapter's get() method and adds lazy-loading and pagination
-    api.get('/products').first[:title]
+```ruby
+# Instantiate object
+user = api.get('/user')
+# No extra request made
+user[:name]
+# Extra request to http://api.com/users/ismael to fetch more user data
+user[:last_name]
+```
     
-    # This delegates directory to MyCustomAdapter#post()
-    api.post('/products', :title => 'Foo', :price => 100.0)
+This works for objects in collections too.
 
-## finding a single resource
+    # JSON collection
+    {
+      'users': {
+        'total_entries': 100,
+        'page': 1,
+        'per_page': 2,
+        'href': 'http://api.com/users',
+        'entries': [
+          {
+            'name': 'Ismael',
+            'href': 'http://api.com/users/ismael'
+          },
+          {
+            'name': 'John',
+            'href': 'http://api.com/users/john'
+          }
+        ]
+      }
+    }
 
-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.
+ 
+```ruby
+# Instantiate collection
+users = api.get('/users') # no request yet
+
+users.total_entries # => 100 # request made
+users.size # => 2, current page
+users.each ... # iterate current page
+users.current_page # => 1
+users.has_next_page? # => true
+users.next_page # => 2
+
+# Access entry. No request made
+ismael = users.first
+ismael[:name] # => 'ismael'
+ismael[:last_name'] #=> request made to http://api.com/users/ismael
+```
 
-    resources = api.get('/my/resources')
-    resource = resources.get_one('foobar')
-    
-That delegates to Adapter#get_one passing 2 arguments: the list's href and the passed name or identifier, so:
+## Per instance configuration
+
+You can configure some variables on a per-instance basis. To configure the attribute name used to access a resource's URL (defaults to :href):
 
 ```ruby
-class ApiBee::Adapters::Special
-  # ...
-  def get_one(href, id)
-    get "#{href}/#{id}"
-  end
+api = ApiBee.setup(MyCustomAdapter) do |config|
+  config.uri_property_name = :uri # use :uri instead
 end
 ```
 
-## Lazy loading
+## Adapter-wide configuration
 
-ApiBee wraps your adapters in lazy-loading objects. API calls will only be issued when accessing or iterating data.
+You can declare configuration in the adapter definition itself, too. Just define the config_api_bee class method in your adapter:
 
-The 'href' property in entities will be used to load more data. For example:
+```ruby
+class MyCustomAdapter
+  
+  def get(path, options)
+    # ...
+  end
+  
+  def self.config_api_bee(config)
+    config.uri_property_name = :uri
+  end
+end
+
+api = ApiBee.setup(MyCustomAdapter) # instance is configured correctly
+```
+
+## 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.
 
-    # /resources
-    [
-      {
-        'title': 'Foo bar',
-        'href': '/resources/foo-bar'
-      }
-    ]
-    
-    # /resources/foo-bar
-    {
-      'title': 'Foo bar',
-      'description': 'Foo description'
-    }
-    
 ```ruby
-api = ApiBee.get(:some_adapter)
+api = ApiBee.setup(MyCustomAdapter) do |config|
+  config.expose :delete, :post
+end
 
-resources = api.get('/resources') # no API call is made
+# This still wraps your adapter's get() method and adds lazy-loading and pagination
+api.get('/products').first[:title]
 
-resource = resources.first # call to /resources is made
+# This delegates directly to MyCustomAdapter#post()
+api.post('/products', :title => 'Foo', :price => 100.0)
+```
 
-resource['title'] # => 'Foo bar', title data available
+## finding a single resource
 
-resource['description'] # => 'Foo description'. Makes internal new request to /resources/foo-bar
+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.
+
+```ruby
+resources = api.get('/my/resources')
+resource = resources.get_one('foobar')
 ```
-    
-    
+
+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 get_one(href, id)
+    get "#{href}/#{id}"
+  end
+end
+``` 
+
 ## Hash adapter
 
 ApiBee ships with an in-memory Hash adapter so it can be use with test/local data (for example a YAML file).
 
+
 ```ruby
 api = ApiBee.setup(:hash, YAML.load_file('./my_data.yml'))
     
@@ -152,4 +220,4 @@ 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
+See [examples/github_api.rb](https://github.com/ismasan/ApiBee/blob/master/examples/github_api.rb) for an adapter that paginates Github's API by decorating it's results with ApiBee's required pagination properties

data/api_bee.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Ismael Celis"]
   s.email       = ["ismaelct@gmail.com"]
-  s.homepage    = ""
-  s.summary     = %q{Small Ruby client for discoverable, paginated JSON APIs}
-  s.description = %q{API Bee is a small client / spec for a particular style of JSON API. USe Hash adapter for local data access.}
+  s.homepage    = "https://github.com/ismasan/ApiBee"
+  s.description     = %q{Small Ruby client for discoverable, lazily-loaded, paginated JSON APIs}
+  s.summary = %q{API Bee is a small client / spec for a particular style of JSON API. Use Hash adapter for local data access.}
 
   s.rubyforge_project = "api_bee"
 

data/examples/github_api.rb

@@ -9,6 +9,10 @@ require 'json'
 #
 class GithubAdapter
   
+  def self.config_api_bee(config)
+    config.uri_property_name = :url
+  end
+  
   def initialize
     @url = URI.parse('https://api.github.com')
     @http = Net::HTTP.new(@url.host, @url.port)
@@ -27,14 +31,12 @@ class GithubAdapter
     
     if response.kind_of?(Net::HTTPOK)
       results = JSON.parse response.body
-      results = if results.is_a?(Array)
+      if results.is_a?(Array)
         # decorate returned array so it complies with APiBee's pagination params
         paginate results, options, path, response
       else
         results
       end
-      
-      results
     else
       nil
     end
@@ -80,9 +82,7 @@ end
 
 ## Instantiate your wrapped API
 
-api = ApiBee.setup(GithubAdapter) do |config|
-  config.uri_property_name = :url
-end
+api = ApiBee.setup(GithubAdapter)
 
 repos = api.get('/users/ismasan/repos')
 

data/lib/api_bee/adapters/hash.rb

@@ -12,7 +12,7 @@ module ApiBee
       
       def get(href, opts = {})
         segments = parse_href(href)
-        found = segments.inject(data) do |mem,i|
+        segments.inject(data) do |mem,i|
           case mem
           when ::Hash
             handle_hash_data mem, i, opts
@@ -22,7 +22,6 @@ module ApiBee
             mem
           end
         end
-        found
       end
       
       def get_one(href, id)

data/lib/api_bee/node.rb

@@ -1,5 +1,11 @@
 module ApiBee
   
+  # == API response objects
+  #
+  # A node wraps Hash data returned by adapter.get(path)
+  # It inspects the returned data and tries to add lazy-loading of missing attributes (provided there is an :href attribute)
+  # and pagination (see Node::List)
+  #
   class Node
     
     def self.simbolized(hash)
@@ -9,6 +15,19 @@ module ApiBee
       end
     end
     
+    # Factory. Inspect passed attribute hash for pagination fields and reurns one of Node::List for paginated node lists
+    # or Node::Single for single nodes
+    # A node (list or single) may contain nested lists or single nodes. This is handled transparently by calling Node.resolve
+    # when accessing nested attributes of a node.
+    #
+    # Example:
+    #
+    #   node = Node.resolve(an_adapter, config_object, {:total_entries => 10, :href => '/products', :entries => [...]})
+    #   # node is a Node::List because is has pagination fields
+    #
+    #   node = Node.resolve(an_adapter, config_object, {:name => 'Ismael', :bday => '11/29/77'})
+    #   # node is a Node::Single because it doesn't represent a paginated list
+    #
     def self.resolve(adapter, config, attrs, href = nil)
       attrs = simbolized(attrs)
       keys = attrs.keys.map{|k| k.to_sym}
@@ -33,6 +52,24 @@ module ApiBee
       @attributes
     end
     
+    # Lazy loading attribute accessor.
+    # Attempts to look for an attribute in this node's present attributes
+    # If the attribute is missing and the node has a :href attribute pointing to more data for this resource
+    # it will delegate to the adapter for more data, update it's attributes and return the found value, if any
+    #
+    # Example:
+    #
+    #   data = {
+    #     :href => '/products/6',
+    #     :title => 'Ipod'
+    #   }
+    #
+    #   node = Node.resolve(adapter, config, data)
+    #
+    #   node[:title] # => 'Ipod'. 
+    #
+    #   node[:price] # new request to /products/6
+    #
     def [](attribute_name)
       if respond_to?(attribute_name)
         send attribute_name
@@ -73,14 +110,54 @@ module ApiBee
       @complete = true
     end
     
+    # == Single node
+    #
+    # Resolved when initial data hash doesn't include pagination attributes
+    #
     class Single < Node
 
     end
-
+    
+    # == Paginated node list
+    #
+    # Resolved by Node.resolve when initial data hash contains pagination attributes :total_entries, :href and :entries
+    # Note that these are the default values for those fields and they can be configured per-API via the passed config object.
+    #
+    # A Node::List exposes methods useful for paginating a list of nodes.
+    #
+    # Example:
+    #
+    #   data = {
+    #     :total_entries => 10,
+    #     :href => '/products',
+    #     :page => 1,
+    #     :per_page => 20,
+    #     :entries => [
+    #        {
+    #          :title => 'Ipod'
+    #        },
+    #        {
+    #          :title => 'Ipad'
+    #        },
+    #        ...
+    #      ]
+    #   }
+    #
+    #   list = Node.resolve(adapter, config, data)
+    #   list.current_page # => 1
+    #   list.has_next_page? # => true
+    #   list.next_page # => 2
+    #   list.size # => 20
+    #   list.each ... # iterate current page
+    #   list.first #=> an instance of Node::Single
+    #
     class List < Node
       
       DEFAULT_PER_PAGE = 100
       
+      # Get one resource from this list
+      # Delegates to adapter.get_one(href, id) and resolves result.
+      #
       def get_one(id)
         data = @adapter.get_one(@href, id)
         data.nil? ? nil : Node.resolve(@adapter, @config, data, @href)

data/lib/api_bee/version.rb

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

data/lib/api_bee.rb

@@ -2,22 +2,52 @@ require 'ostruct'
 module ApiBee
   
   class << ApiBee
-    attr_reader :config
     
+    # Setup and instantiates a new API proxy (ApiBee::Proxy)
+    # by wrapping a bundled or custom API adapter and passing optional arguments
+    #
+    # When a hash is passed as the adapter class, it will look for that class file in 
+    # the bundled adapters directory:
+    #
+    #    ApiBee.setup(:hash, {})
+    #
+    # Looks for ApiBee::Adapters::Hash in lib/api_bee/adapters
+    #
+    # You can pass a custom adapter class
+    #
+    # Example:
+    #
+    #   class MyAdapter
+    #     def initialize(api_key)
+    #      @url = 'http://myservice.com'
+    #     end
+    #
+    #     def get(path, options = {})
+    #       # Fetch data from your service here
+    #     end
+    #   end
+    #
+    #   api = ApiBee.setup(MyAdapter, 'MY_API_KEY')
+    #
+    # That gives you an instance of ApiBee::Proxy wrapping an instance of your MyAdapter initialized with your key.
+    #
     def setup(adapter_klass, *args)
       
-      adapter = if adapter_klass.is_a?(::Symbol)
+      adapter_klass = (
         require File.join('api_bee', 'adapters', adapter_klass.to_s)
         klass = adapter_klass.to_s.gsub(/(^.{1})/){$1.upcase}
-        Adapters.const_get(klass).new(*args)
-      else
-        adapter_klass.new *args
-      end
-
-      raise NoMethodError, "Adapter must implement #get(path, *args) method" unless adapter.respond_to?(:get)
+        Adapters.const_get(klass)
+      ) if adapter_klass.is_a?(Symbol)
       
       config = new_config
+      # If adapter-wide config method
+      adapter_klass.config_api_bee(config) if adapter_klass.respond_to?(:config_api_bee)
+      # If config block passed per api instance
       yield config if block_given?
+      
+      adapter = adapter_klass.new(*args)
+      raise NoMethodError, "Adapter must implement #get(path, *args) method" unless adapter.respond_to?(:get)
+      
       Proxy.new adapter, config
     end
     
@@ -38,6 +68,16 @@ module ApiBee
     
     class Config < OpenStruct
       
+      # Delegate method calls to your wrapped adapter
+      #
+      # Example:
+      #
+      #   api = ApiBee.setup(TwitterAdapter) do |config|
+      #     config.expose :post_message, :delete_message
+      #   end
+      #
+      # Now calls to api.post_message and api.delete_message will be delegated to an instance of TwitterAdapter
+      #
       def expose(*fields)
         self.adapter_delegators = fields
       end

data/spec/setup_spec.rb

@@ -41,7 +41,47 @@ describe 'ApiBee.setup' do
     
   end
   
-  context 'configuration' do
+  describe 'global adapter configuration' do
+    
+    before do
+      require 'api_bee/adapters/hash'
+      @adapter_klass = Class.new(ApiBee::Adapters::Hash) do
+        
+        def self.config_api_bee(config)
+          config.expose :fetch
+          config.uri_property_name = :uri
+        end
+        
+        def fetch(*args)
+          @data.fetch *args
+        end
+        
+      end
+      
+      @api = ApiBee.setup(@adapter_klass, {
+        :user => {
+          :name => 'ismael 1',
+          :uri => '/users/ismael1'
+        }
+      })
+    end
+    
+    it 'should have configure defaults for all instances of adapter' do
+      user = @api.get('/user')
+      user[:name].should == 'ismael 1'
+      @api.adapter.should_receive(:get).with('/users/ismael1').and_return(:last_name => 'Celis')
+
+      user[:last_name].should == 'Celis'
+    end
+    
+    it 'should delegate configured methods to adapter' do
+      @api.fetch(:user, 'foo').should == {:name => 'ismael 1', :uri => '/users/ismael1'}
+      @api.fetch(:blah, 'foo').should == 'foo'
+    end
+    
+  end
+  
+  context 'per-instance configuration' do
     
     before do
       @api1 = ApiBee.setup(:hash, {

metadata

@@ -2,7 +2,7 @@
 name: api_bee
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors: 
 - Ismael Celis
@@ -10,10 +10,10 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-22 00:00:00 Z
+date: 2011-09-26 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.
+description: Small Ruby client for discoverable, lazily-loaded, paginated JSON APIs
 email: 
 - ismaelct@gmail.com
 executables: []
@@ -41,7 +41,7 @@ files:
 - spec/node_spec.rb
 - spec/setup_spec.rb
 - spec/spec_helper.rb
-homepage: ""
+homepage: https://github.com/ismasan/ApiBee
 licenses: []
 
 post_install_message: 
@@ -67,7 +67,7 @@ rubyforge_project: api_bee
 rubygems_version: 1.8.6
 signing_key: 
 specification_version: 3
-summary: Small Ruby client for discoverable, paginated JSON APIs
+summary: API Bee is a small client / spec for a particular style of JSON API. Use Hash adapter for local data access.
 test_files: 
 - spec/hash_adapter_spec.rb
 - spec/node_spec.rb