api_bee 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in api_bee.gemspec
+gemspec
+
+group :test do
+  gem 'rspec' # dev, test
+end
+

data/README.mkd

@@ -0,0 +1,119 @@
+# API BEE
+
+API Bee is a small client / spec for a particular style of JSON API.
+
+These APIs must
+
+* Expose resource collections as paginated lists, with entries and paging properties.
+* Resource entities in collections must include an 'href' property pointing to the individual resource, so as to provide a degree of discoverability.
+
+A single resource might look like:
+
+    {
+      'name':        'Foo',
+      'description': 'foo resoruce',
+      'href':        'http://api.myservice.com/resources/foo'
+    }
+    
+A resource collection looks like:
+
+    {
+      'href': 'http://api.myservice.com/resources',
+      'total_entries': 100,
+      'page': 1,
+      'per_page': 10,
+      'entries': [
+        {
+          'name':        'Foo',
+          'description': 'foo resoruce',
+          'href':         'http://api.myservice.com/resources/foo'
+        },
+        {
+          'name':        'Bar',
+          'description': 'bar resoruce',
+          'href':        'http://api.myservice.com/resources/bar'
+        },
+        ...
+      ]
+    }
+    
+Collection resources must include the fields 'href', 'total_entries', 'page', 'per_page' and 'entries'. This allows clients to paginate and fetch more pages.
+
+## Adapters
+
+It is up to individual adapters to talk to different services, handle auth, etc. An adapter must at least implement 'get' for read-only APIs.
+
+```ruby
+class ApiBee::Adapters::Special
+  def get(path, options = {})
+    # fetch JSON from remote API, passing pagination options if available
+  end
+end
+```
+
+The use it:
+
+```ruby
+api = ApiBee.setup :special, optional_custom_data
+
+api.get('/my/resources').each do |r|
+  r[:name]
+end
+```
+
+## Lazy loading
+
+ApiBee wraps your adapters in lazy-loading objects. API calls will only be issued when accessing or iterating data.
+
+The 'href' property in entities will be used to load more data. For example:
+
+    # /resources
+    [
+      {
+        'title': 'Foo bar',
+        'href': '/resources/foo-bar'
+      }
+    ]
+    
+    # /resources/foo-bar
+    {
+      'title': 'Foo bar',
+      'description': 'Foo description'
+    }
+    
+```ruby
+api = ApiBee.get(:some_adapter)
+
+resources = api.get('/resources') # no API call is made
+
+resource = resources.first # call to /resources is made
+
+resource['title'] # => 'Foo bar', title data available
+
+resource['description'] # => 'Foo description'. Makes internal new request to /resources/foo-bar
+```
+    
+    
+## 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'))
+    
+products = api.get('/products') # => ApiBee::Node::List
+    
+products.first # => ApiBee::Node::Single
+    
+products.each() # iterate current page
+    
+products.current_page # => 1
+    
+products.paginate(:page => 2, :per_page => 4) # => ApiBee::Node::List # Next page
+    
+products.has_next_page? # => false
+    
+products.has_prev_page? # => true
+    
+products.prev_page # => 1
+``` 

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new('spec')
+
+# If you want to make this the default task
+task :default => :spec

data/api_bee.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "api_bee/version"
+
+Gem::Specification.new do |s|
+  s.name        = "api_bee"
+  s.version     = ApiBee::VERSION
+  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.rubyforge_project = "api_bee"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/examples/catalog.yml

@@ -0,0 +1,61 @@
+:products:
+  :total_entries: 6
+  :href: /products
+  :entries:
+    -
+      :title: P1
+      :id: p1
+      :price: 100
+    -
+      :title: P2
+      :id: p2
+      :price: 200 
+    -
+      :title: P3
+      :id: p3
+      :price: 300
+    -
+      :title: P4
+      :id: p4
+      :price: 400
+    -
+      :title: P5
+      :id: p5
+      :price: 500
+    -
+      :title: P6
+      :id: p6
+      :price: 600
+      
+:collections:
+  :total_entries: 2
+  :href: /collections
+  :entries:
+    -
+      :title: Collection 1
+      :id: c1
+      :products:
+        :total_entries: 2
+        :page: 1
+        :per_page: 1
+        :href: /products
+        :entries:
+          -
+            :href: /products/p1
+          -
+            :href: /products/p2
+            
+    -
+      :title: Collection 2
+      :id: c2
+      :products:
+        :total_entries: 2
+        :page: 1
+        :per_page: 1
+        :href: /products
+        :entries:
+          -
+            :href: /products/p1
+          -
+            :href: /products/p5
+    

data/examples/yaml_catalog.rb

@@ -0,0 +1,23 @@
+$LOAD_PATH.unshift '../lib'
+require 'yaml'
+require 'api_bee'
+
+api = ApiBee.setup(:hash, YAML.load_file('./catalog.yml'))
+
+collection = api.get('/collections/c1')
+
+p collection[:title]
+
+products = collection[:products]
+
+puts "First page"
+
+products.each do |p|
+  p p[:title]
+end
+
+puts "Second page"
+
+products.paginate(:page => products.next_page, :per_page => 2).each do |p|
+  p p[:title]
+end

data/lib/api_bee/adapters/hash.rb

@@ -0,0 +1,72 @@
+module ApiBee
+  
+  module Adapters
+    
+    class Hash
+      
+      attr_reader :data
+      
+      def initialize(*args)
+        @data = args.last
+      end
+      
+      def get(href, opts = {})
+        segments = parse_href(href)
+        found = segments.inject(data) do |mem,i|
+          case mem
+          when ::Hash
+            handle_hash_data mem, i, opts
+          when ::Array
+            handle_array_data mem, i
+          else
+            mem
+          end
+        end
+        found
+      end
+      
+      protected
+      
+      def parse_href(href)
+        href.gsub(/^\//, '').split('/')
+      end
+      
+      def handle_hash_data(hash, key, opts = {})
+        if is_paginated?(hash) # paginated collection
+          handle_array_data hash[:entries], key
+        else # /products. Might be a paginated list
+          r = hash[key.to_sym]
+          if opts.keys.include?(:page) && opts.keys.include?(:per_page) && r.kind_of?(::Hash) && is_paginated?(r)
+            paginate(r, opts[:page], opts[:per_page])
+          else
+            r
+          end
+        end
+      end
+      
+      def handle_array_data(array, key)
+        if array[0].kind_of?(::Hash)
+          array.find {|e| e[:id] == key}
+        else
+          array
+        end
+      end
+      
+      def is_paginated?(hash)
+        hash[ApiBee.config.uri_property_name] && hash[:total_entries]
+      end
+      
+      def paginate(list, page, per_page)
+        from = page * per_page - per_page
+        to =  page * per_page
+        list[:entries] = list[:entries].to_a[from...to]
+        list[:current_page] = page
+        list[:per_page] = per_page
+        list
+      end
+      
+    end
+    
+  end
+  
+end

data/lib/api_bee/node.rb

@@ -0,0 +1,140 @@
+module ApiBee
+  
+  class Node
+    
+    def self.resolve(adapter, 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
+      else
+        Single.new adapter, attrs
+      end
+    end
+    
+    attr_reader :adapter
+    
+    def initialize(adapter, attrs)
+      @adapter = adapter
+      @attributes = {}
+      update_attributes attrs
+    end
+    
+    def [](attribute_name)
+      if value = @attributes[attribute_name]
+        resolve_values_to_nodes value
+      elsif has_more? # check whether there's more info in API
+        load_more!
+        self[attribute_name] # recurse once
+      else
+        nil
+      end
+    end
+    
+    protected
+    
+    def update_attributes(attrs)
+      @attributes.merge!(attrs)
+    end
+    
+    def resolve_values_to_nodes(value)
+      case value
+      when ::Hash
+        Node.resolve @adapter, value
+      when ::Array
+        value.map {|v| resolve_values_to_nodes(v)} # recurse
+      else
+        value
+      end
+    end
+    
+    def has_more?
+      !@complete && @attributes[ApiBee.config.uri_property_name]
+    end
+    
+    def load_more!
+      more_data = @adapter.get(@attributes[ApiBee.config.uri_property_name])
+      update_attributes more_data if more_data
+      @complete = true
+    end
+    
+    class Single < Node
+
+    end
+
+    class List < Node
+      
+      DEFAULT_PER_PAGE = 100
+      
+      def total_entries
+        @attributes[:total_entries].to_i
+      end
+      
+      def size
+        entries.size
+      end
+      
+      def current_page
+        (@attributes[:current_page] || 1).to_i
+      end
+      
+      def per_page
+        (@attributes[:per_page] || DEFAULT_PER_PAGE).to_i
+      end
+      
+      def total_pages
+        div = total_entries / per_page
+        div < 1 ? 1 : div
+      end
+      
+      def next_page
+        current_page + 1
+      end
+      
+      def prev_page
+        current_page - 1
+      end
+      
+      def pages
+        (1..total_pages).to_a
+      end
+      
+      def has_next_page?
+        next_page <= total_pages
+      end
+      
+      def has_prev_page?
+        current_page > 1
+      end
+      
+      def first
+        entries.first
+      end
+      
+      def last
+        entries.last
+      end
+      
+      def each(&block)
+        entries.each(&block)
+      end
+      
+      def 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
+      end
+      
+      protected
+      
+      def entries
+        @entries ||= (self[:entries] || [])
+      end
+
+    end
+    
+  end
+  
+end

data/lib/api_bee/proxy.rb

@@ -0,0 +1,17 @@
+module ApiBee
+  
+  class Proxy
+    
+    attr_reader :adapter
+    
+    def initialize(adapter)
+      @adapter = adapter
+    end
+    
+    def get(href)
+      Node.resolve @adapter, ApiBee.config.uri_property_name => href
+    end
+    
+  end
+  
+end

data/lib/api_bee/version.rb

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

data/lib/api_bee.rb

@@ -0,0 +1,39 @@
+require 'ostruct'
+module ApiBee
+  
+  class << ApiBee
+    attr_reader :config
+    
+    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}
+        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)
+      Proxy.new adapter
+    end
+    
+    def config
+      @config ||= OpenStruct.new
+    end
+    
+  end
+  
+  # Defaults
+  self.config.uri_property_name = :href
+  
+  module Adapters
+    
+  end
+  
+end
+
+require 'api_bee/proxy'
+require 'api_bee/node'

data/spec/hash_adapter_spec.rb

@@ -0,0 +1,96 @@
+require 'spec_helper'
+require 'api_bee/adapters/hash'
+
+describe ApiBee::Adapters::Hash do
+  
+  before do
+    @data = {
+      # Collections
+      :collections        => [
+        {
+          :title          => 'Catalog',
+          :id             => 'catalog',
+          :foos           => [1,2,3,4],
+          :products       => {
+            :total_entries    => 4,
+            :current_page     => 1,
+            :per_page         => 4,
+            :href             => '/collections/catalog/products',
+            :entries            => [
+              {
+                :id           => 'foo-1',
+                :href         => '/products/foo-1'
+              },
+              {
+                :id           => 'foo-2',
+                :title        => 'Foo 2',
+                :href         => '/products/foo-2'
+              },
+              {
+                :id           => 'foo-3',
+                :title        => 'Foo 3',
+                :href         => '/products/foo-3'
+              },
+              {
+                :id           => 'foo-4',
+                :title        => 'Foo 4',
+                :href         => '/products/foo-4'
+              }
+            ]
+          }
+        }
+      ]
+    }
+    
+    @adapter        = ApiBee::Adapters::Hash.new(@data)
+  end
+  
+  context 'accessing single nodes' do
+    
+    before do
+      @collection     = @adapter.get('/collections/catalog')
+    end
+    
+    it 'should find node by :id' do
+      @collection[:title].should == 'Catalog'
+      @collection[:id].should == 'catalog'
+    end
+    
+    it 'should find entries in paginated collections' do
+      product = @adapter.get('/collections/catalog/products/foo-2')
+      product[:title].should == 'Foo 2'
+    end
+    
+    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[:per_page].should == 4
+      products[:entries].size.should == 4
+    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'
+    end
+  end
+  
+  context 'accessing node collections' do
+    
+    before do
+      @list = @adapter.get('/collections/catalog/foos')
+    end
+    
+    it 'should return array' do
+      @list.size.should == 4
+      @list.should == [1,2,3,4]
+    end
+  end
+  
+end

data/spec/node_spec.rb

@@ -0,0 +1,168 @@
+require 'spec_helper'
+
+describe ApiBee do
+  
+  before do
+    @data = {
+      # Products
+      :products         => {
+        :href => '/products',
+        :total_entries => 6,
+        :entries => [
+          {
+            :title        => 'Foo 1',
+            :id           => 'foo-1',
+            :price        => 100,
+            :description  => 'Foo 1 desc'
+          },
+          {
+            :title        => 'Foo 2',
+            :id           => 'foo-2',
+            :price        => 200,
+            :description  => 'Foo 2 desc'
+          },
+          {
+            :title        => 'Foo 3',
+            :id           => 'foo-3',
+            :price        => 300,
+            :description  => 'Foo 3 desc'
+          },
+          {
+            :title        => 'Foo 4',
+            :id           => 'foo-4',
+            :price        => 400,
+            :description  => 'Foo 4 desc'
+          },
+          {
+            :title        => 'Foo 5',
+            :id           => 'foo-5',
+            :price        => 500,
+            :description  => 'Foo 5 desc'
+          },
+          {
+            :title        => 'Foo 6',
+            :id           => 'foo-6',
+            :price        => 600,
+            :description  => 'Foo 6 desc'
+          }
+        ]
+      },
+      # Collections
+      :collections        => [
+        {
+          :title          => 'Catalog',
+          :id             => 'catalog',
+          :products       => {
+            :href           => '/products',
+            :total_entries    => 4,
+            :current_page     => 1,
+            :per_page         => 2,
+            :href             => '/products',
+            :entries            => [
+              {
+                :id           => 'foo-1',
+                :href         => '/products/foo-1'
+              },
+              {
+                :id           => 'foo-2',
+                :title        => 'Foo 2',
+                :href         => '/products/foo-2'
+              }
+            ]
+          }
+        }
+      ]
+    }
+    
+  end
+  
+  describe '.resolve' do
+    
+    before do
+      @adapter = mock('Adapter')
+    end
+    
+    it 'should resolve single nodes' do
+      node = ApiBee::Node.resolve(@adapter, {: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 resolve paginated lists' do
+      node = ApiBee::Node.resolve(@adapter, {:title => 'Blah', :total_entries => 4, :href => '/products'})
+      node.total_entries.should == 4
+      node.adapter.should == @adapter
+      node.should be_kind_of(ApiBee::Node::List)
+    end
+  end
+  
+  context 'lazy loading' do
+    before do
+      require 'api_bee/adapters/hash'
+      @adapter = ApiBee::Adapters::Hash.new(@data)
+      ApiBee::Adapters::Hash.should_receive(:new).with(@data).and_return @adapter
+      @api = ApiBee.setup(:hash, @data)
+    end
+    
+    it 'should return a Proxy' do
+      @api.should be_kind_of(ApiBee::Proxy)
+    end
+    
+    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
+        node = @api.get('/collections/catalog')
+        node[:title].should == 'Catalog'
+        node[:id].should == 'catalog'
+      end
+    end
+    
+    describe 'paginated lists' do
+      before do
+        @collection = @api.get('/collections/catalog')
+        @products = @collection[:products]
+      end
+      
+      it 'should have a paginator interface' do
+        @products.total_entries.should == 4
+        @products.size.should == 2
+        @products.total_pages.should == 2
+        @products.current_page.should == 1
+        @products.pages.should == [1,2]
+        @products.has_next_page?.should be_true
+        @products.has_prev_page?.should be_false
+      end
+      
+      it 'should iterate the first page' do
+        titles = []
+        klasses = []
+        @products.each {|p| titles << p[:title]}
+        @products.each {|p| klasses << p.class}
+        klasses.should == [ApiBee::Node::Single, ApiBee::Node::Single]
+        titles.should == ['Foo 1', 'Foo 2']
+        @products.first[:title].should == 'Foo 1'
+        @products.last[:title].should == 'Foo 2'
+      end
+      
+      it 'should navigate to the second page' do
+        @products = @products.paginate(:page => 2, :per_page => 2)
+        titles = []
+        klasses = []
+        @products.each {|p| titles << p[:title]}
+        @products.each {|p| klasses << p.class}
+        @products.current_page.should == 2
+        @products.total_entries.should == 6
+        @products.size.should == 2
+        klasses.should == [ApiBee::Node::Single, ApiBee::Node::Single]
+        titles.should == ['Foo 3', 'Foo 4']
+        @products.first[:title].should == 'Foo 3'
+        @products.last[:title].should == 'Foo 4'
+      end
+      
+    end
+    
+  end
+  
+end

data/spec/setup_spec.rb

@@ -0,0 +1,60 @@
+require 'spec_helper'
+
+describe 'ApiBee.setup' do
+  
+  describe 'with bundled adapter' do
+    
+    it 'should return a proxy to instantiated adapter' do
+      api = ApiBee.setup(:hash, {})
+      api.adapter.should be_kind_of(ApiBee::Adapters::Hash)
+    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
+      
+      class CustomAdapter
+        attr_reader :opts
+        def initialize(opts)
+          @opts = opts
+        end
+        
+        def get(path, *args);end
+      end
+      
+    end
+    
+    it 'shoud instantiate adapter with options' do
+      api = ApiBee.setup(CustomAdapter, :one => 1)
+      api.adapter.should be_kind_of(CustomAdapter)
+      api.adapter.opts.should == {:one => 1}
+    end
+    
+  end
+  
+  describe 'with adapter without #get method' do
+    it 'should complain' do
+      lambda {
+        ApiBee.setup(String)
+      }.should raise_error("Adapter must implement #get(path, *args) method")
+    end
+    
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+require 'rubygems'
+require 'bundler'
+
+$TESTING = true
+
+Bundler.setup(:default, :test)
+
+$LOAD_PATH.unshift(File.join(File.expand_path(File.dirname(__FILE__)), '..', 'lib'))
+
+ENV['RACK_ENV'] = 'test'
+
+require 'api_bee'
+
+RSpec.configure do |config|
+  # some (optional) config here
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: api_bee
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Ismael Celis
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-09-19 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.
+email: 
+- ismaelct@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rspec
+- Gemfile
+- README.mkd
+- Rakefile
+- api_bee.gemspec
+- examples/catalog.yml
+- examples/yaml_catalog.rb
+- lib/api_bee.rb
+- lib/api_bee/adapters/hash.rb
+- lib/api_bee/node.rb
+- lib/api_bee/proxy.rb
+- lib/api_bee/version.rb
+- spec/hash_adapter_spec.rb
+- spec/node_spec.rb
+- spec/setup_spec.rb
+- spec/spec_helper.rb
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: api_bee
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: Small Ruby client for discoverable, paginated JSON APIs
+test_files: 
+- spec/hash_adapter_spec.rb
+- spec/node_spec.rb
+- spec/setup_spec.rb
+- spec/spec_helper.rb