her 0.2.1 → 0.2.2

data/README.md

@@ -1,6 +1,6 @@
 # Her
 
-Her is an ORM (Object Relational Mapper) that maps REST resources to Ruby objects. It is designed to build applications that are powered by a RESTful API and no database.
+Her is an ORM (Object Relational Mapper) that maps REST resources to Ruby objects. It is designed to build applications that are powered by a RESTful API instead of a database.
 
 [![Build Status](https://secure.travis-ci.org/remiprev/her.png)](http://travis-ci.org/remiprev/her)
 
@@ -56,7 +56,7 @@ User.find(1)
 
 ## Middleware
 
-Since Her relies on [Faraday](https://github.com/technoweenie/faraday) to send HTTP requests, you can add additional middleware to handle requests and responses.
+Since Her relies on [Faraday](https://github.com/technoweenie/faraday) to send HTTP requests, you can add additional middleware to handle requests and responses. Using a block in the `setup` call, you have access to Faraday’s `builder` object and are able to customize the middleware stack used on each request and response.
 
 ### Authentication
 
@@ -64,14 +64,19 @@ Her doesn’t support any kind of authentication. However, it’s very easy to i
 
 ```ruby
 class MyAuthentication < Faraday::Middleware
+  def initialize(app, options={})
+    @options = options
+  end
+
   def call(env)
-    env[:request_headers]["X-API-Token"] = "bb2b2dd75413d32c1ac421d39e95b978d1819ff611f68fc2fdd5c8b9c7331192"
+    env[:request_headers]["X-API-Token"] = @options[:token] if @options.include?(:token)
     @app.call(env)
   end
 end
 
 Her::API.setup :base_uri => "https://api.example.com" do |builder|
-  builder.use MyAuthentication
+  # This token could be stored in the client session
+  builder.use MyAuthentication, :token => "bb2b2dd75413d32c1ac421d39e95b978d1819ff611f68fc2fdd5c8b9c7331192"
 end
 ```
 
@@ -91,14 +96,14 @@ By default, Her handles JSON data. It expects the resource/collection data to be
 [{ "id" : 1, "name" : "Tobias Fünke" }]
 ```
 
-However, you can define your own parsing method, using a response middleware. The middleware is expected to set `env[:body]` to a hash with three keys: `data`, `errors` and `metadata`. The following code enables parsing JSON data and treating the result as first-level properties. Using the builder block, we then replace the default parser.
+However, you can define your own parsing method, using a response middleware. The middleware is expected to set `env[:body]` to a hash with three keys: `data`, `errors` and `metadata`. The following code enables parsing JSON data and treating the result as first-level properties. Using the builder block, we then replace the default parser with our custom parser.
 
 ```ruby
 class MyCustomParser < Faraday::Response::Middleware
   def on_complete(env)
     json = MultiJson.load(env[:body], :symbolize_keys => true)
     env[:body] = {
-      :data => json[:data],
+      :data => json[:result],
       :errors => json[:errors],
       :metadata => json[:metadata]
     }
@@ -106,10 +111,10 @@ class MyCustomParser < Faraday::Response::Middleware
 end
 
 Her::API.setup :base_uri => "https://api.example.com" do |builder|
-  builder.delete Her::Middleware::DefaultParseJSON
-  builder.use MyCustomParser
+  # We use the `swap` method to replace Her’s default parser middleware
+  builder.swap Her::Middleware::DefaultParseJSON, MyCustomParser
 end
-# User.find(1) will now expect "https://api.example.com/users/1" to return something like '{ "data" => { "id": 1, "name": "Tobias Fünke" }, "errors" => [] }'
+# User.find(1) will now expect "https://api.example.com/users/1" to return something like '{ "result" => { "id": 1, "name": "Tobias Fünke" }, "errors" => [] }'
 ```
 
 ### OAuth
@@ -136,7 +141,8 @@ TWITTER_CREDENTIALS = {
 }
 
 Her::API.setup :base_uri => "https://api.twitter.com/1/" do |builder|
-  builder.use FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
+  # We need to insert the middleware at the beginning of the stack (hence the `insert 0`)
+  builder.insert 0, FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
 end
 
 class Tweet
@@ -161,12 +167,26 @@ In your Ruby code:
 
 ```ruby
 class MyCache
-  def write(key, value); end
-  def read(key); end
-  def fetch(key, &block); end
+  def initialize
+    @cache = {}
+  end
+
+  def write(key, value)
+    @cache[key] = value
+  end
+
+  def read(key)
+    @cache[key]
+  end
+
+  def fetch(key, &block)
+    return value = read(key) if value.nil?
+    write key, yield
+  end
 end
 
 # A cache system must respond to `#write`, `#read` and `#fetch`.
+# We should be probably using something like Memcached here, not a global object
 $cache = MyCache.new
 
 Her::API.setup :base_uri => "https://api.example.com" do |builder|
@@ -178,12 +198,15 @@ class User
 end
 
 @user = User.find(1)
-@user = User.find(1) # This request will be fetched from the cache
+# GET /users/1
+
+@user = User.find(1)
+# This request will be fetched from the cache
 ```
 
 ## Relationships
 
-You can define `has_many`, `has_one` and `belongs_to` relationships in your models. The relationship data is handled in two different ways. When parsing a resource from JSON data, if there’s a relationship data included, it will be used to create new Ruby objects.
+You can define `has_many`, `has_one` and `belongs_to` relationships in your models. The relationship data is handled in two different ways. If there’s relationship data when parsing a resource, it will be used to create new Ruby objects.
 
 If no relationship data was included when parsing a resource, calling a method with the same name as the relationship will fetch the data (providing there’s an HTTP request available for it in the API).
 
@@ -210,7 +233,7 @@ class Organization
 end
 ```
 
-If there’s relationship data in the resource, no extra HTTP request is made when calling the `#comments` method and an array of resources are returned:
+If there’s relationship data in the resource, no extra HTTP request is made when calling the `#comments` method and an array of resources is returned:
 
 ```ruby
 @user = User.find(1) # { :data => { :id => 1, :name => "George Michael Bluth", :comments => [{ :id => 1, :text => "Foo" }, { :id => 2, :text => "Bar" }], :role => { :id => 1, :name => "Admin" }, :organization => { :id => 2, :name => "Bluth Company" } }}
@@ -226,21 +249,21 @@ If there’s no relationship data in the resource, an extra HTTP request (to `GE
 @user.comments # => [#<Comment id=1>, #<Comment id=2>] fetched from /users/1/comments
 ```
 
-For `has_one` relationship, an extra HTTP request (to `GET /users/1/role`) is made when calling the `#role` method:
+For `has_one` relationships, an extra HTTP request (to `GET /users/1/role`) is made when calling the `#role` method:
 
 ```ruby
 @user = User.find(1) # { :data => { :id => 1, :name => "George Michael Bluth" }}
 @user.role # => #<Role id=1> fetched from /users/1/role
 ```
 
-For `belongs_to` relationship, an extra HTTP request (to `GET /organizations/2`) is made when calling the `#organization` method:
+For `belongs_to` relationships, an extra HTTP request (to `GET /organizations/2`) is made when calling the `#organization` method:
 
 ```ruby
 @user = User.find(1) # { :data => { :id => 1, :name => "George Michael Bluth", :organization_id => 2 }}
 @user.organization # => #<Organization id=2> fetched from /organizations/2
 ```
 
-However, subsequent calls to `#comments` or `#role` will not trigger the extra HTTP request.
+However, subsequent calls to `#comments`, `#role` and `#organization` will not trigger extra HTTP requests as the data has already been fetched.
 
 ## Hooks
 
@@ -260,8 +283,6 @@ end
 # POST /users&fullname=Tobias+Fünke&internal_id=42
 ```
 
-In the future, adding hooks to all models will be possible, as well as defining and triggering your own hooks (eg. for your custom requests).
-
 ## Custom requests
 
 You can easily define custom requests for your models using `custom_get`, `custom_post`, etc.
@@ -343,12 +364,12 @@ end
 # GET /hello_users/1
 ```
 
-You can include custom variables in your paths:
+You can also include custom variables in your paths:
 
 ```ruby
 class User
   include Her::Model
-  collection_path "/organizations/:organization_id/users/:id"
+  collection_path "/organizations/:organization_id/users"
 end
 
 @user = User.find(1, :_organization_id => 2)
@@ -356,6 +377,10 @@ end
 
 @user = User.all(:_organization_id => 2)
 # GET /organizations/2/users
+
+@user = User.new(:fullname => "Tobias Fünke", :organization_id => 2)
+@user.save
+# POST /organizations/2/users
 ```
 
 ## Multiple APIs
@@ -394,7 +419,7 @@ Category.all
 ## Things to be done
 
 * Better error handling
-* Better documentation
+* Better API documentation (using YARD)
 
 ## Contributors
 
@@ -403,6 +428,7 @@ Feel free to contribute and submit issues/pull requests [on GitHub](https://gith
 * [@jfcixmedia](https://github.com/jfcixmedia)
 * [@EtienneLem](https://github.com/EtienneLem)
 * [@rafaelss](https://github.com/rafaelss)
+* [@tysontate](https://github.com/tysontate)
 
 Take a look at the `spec` folder before you do, and make sure `bundle exec rake spec` passes after your modifications :)
 

data/examples/twitter-oauth/app.rb

@@ -1,5 +1,5 @@
 # Create custom parser
-class TwitterSearchParser < Faraday::Response::Middleware
+class TwitterParser < Faraday::Response::Middleware
   METADATA_KEYS = [:completed_in, :max_id, :max_id_str, :next_page, :page, :query, :refresh_url, :results_per_page, :since_id, :since_id_str]
 
   def on_complete(env)
@@ -21,7 +21,10 @@ TWITTER_CREDENTIALS = {
 }
 
 # Initialize API
-Her::API.setup :base_uri => "https://api.twitter.com/1/", :parse_middleware => TwitterSearchParser, :add_middleware => [FaradayMiddleware::OAuth => TWITTER_CREDENTIALS]
+Her::API.setup :base_uri => "https://api.twitter.com/1/" do |builder|
+  builder.insert 0, FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
+  builder.swap Her::Middleware::DefaultParseJSON, TwitterParser
+end
 
 # Define classes
 class Tweet
@@ -31,12 +34,16 @@ class Tweet
     get "/statuses/home_timeline.json"
   end
 
+  def self.mentions
+    get "/statuses/mentions.json"
+  end
+
   def username
     user[:screen_name]
   end
 end
 
 get "/" do
-  @tweets = Tweet.timeline
+  @tweets = Tweet.mentions
   haml :index
 end

data/examples/twitter-search/Gemfile

@@ -3,6 +3,7 @@ source :rubygems
 gem "sinatra"
 gem "haml"
 gem "thin", :require => false
+gem "faraday_middleware"
 
 gem "her", :path => File.join(File.dirname(__FILE__),"../..")
 

data/examples/twitter-search/app.rb

@@ -12,8 +12,32 @@ class TwitterSearchParser < Faraday::Response::Middleware
   end
 end
 
+class MyCache
+  def initialize
+    @cache = {}
+  end
+
+  def write(key, value)
+    @cache[key] = value
+  end
+
+  def read(key)
+    @cache[key]
+  end
+
+  def fetch(key, &block)
+    return value = read(key) if value.nil?
+    write key, yield
+  end
+end
+
+$cache = MyCache.new
+
 # Initialize API
-Her::API.setup :base_uri => "http://search.twitter.com", :parse_middleware => TwitterSearchParser
+Her::API.setup :base_uri => "http://search.twitter.com" do |builder|
+  builder.swap Her::Middleware::FirstLevelParseJSON, TwitterSearchParser
+  builder.use FaradayMiddleware::Caching, $cache
+end
 
 # Define classes
 class Tweet

data/lib/her/api.rb

@@ -3,14 +3,12 @@ module Her
   # so it knows where to make those requests. In Rails, this is usually done in `config/initializers/her.rb`:
   class API
     # @private
-    attr_reader :base_uri, :middleware
+    attr_reader :base_uri, :middleware, :connection
 
     # Setup a default API connection. Accepted arguments and options are the same as {API#setup}.
-    def self.setup(attrs={}) # {{{
+    def self.setup(attrs={}, &block) # {{{
       @@default_api = new
-      connection = @@default_api.setup(attrs)
-      yield connection.builder if block_given?
-      connection
+      @@default_api.setup(attrs, &block)
     end # }}}
 
     # Setup the API connection.
@@ -60,19 +58,12 @@ module Her
 
       @middleware.flatten!
       middleware = @middleware
-      @connection = Faraday.new(:url => @base_uri) do |builder|
-        middleware.each do |item|
-          klass = item.is_a?(Hash) ? item.keys.first : item
-          args = item.is_a?(Hash) ? item.values.first : nil
-          if args
-            builder.use klass, args
-          else
-            builder.use klass
-          end
+      @connection = Faraday.new(:url => @base_uri) do |connection|
+        middleware.each do |klass|
+          connection.use klass
         end
+        yield connection.builder if block_given?
       end
-      yield @connection.builder if block_given?
-      @connection
     end # }}}
 
     # Define a custom parsing procedure. The procedure is passed the response object and is

data/lib/her/model.rb

@@ -35,8 +35,9 @@ module Her
       extend Her::Model::Paths
 
       # Define default settings
-      collection_path "/#{self.to_s.downcase.pluralize}"
-      resource_path "/#{self.to_s.downcase.pluralize}/:id"
+      base_path = self.name.split("::").last.downcase.pluralize
+      collection_path "/#{base_path}"
+      resource_path "/#{base_path}/:id"
       uses_api Her::API.default_api
     end
   end

data/lib/her/version.rb

@@ -1,3 +1,3 @@
 module Her
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/spec/api_spec.rb

@@ -16,20 +16,52 @@ describe Her::API do
         @api.setup :base_uri => "https://api.example.com"
         @api.base_uri.should == "https://api.example.com"
       end # }}}
+
+      it "sets custom middleware with #use" do # {{{
+        class Foo; end;
+        class Bar; end;
+
+        @api = Her::API.new
+        @api.setup :base_uri => "https://api.example.com" do |builder|
+          builder.use Foo
+          builder.use Bar
+        end
+        @api.connection.builder.handlers.should == [Her::Middleware::FirstLevelParseJSON, Faraday::Request::UrlEncoded, Faraday::Adapter::NetHttp, Foo, Bar]
+      end # }}}
+
+      it "sets custom middleware with #insert" do # {{{
+        class Foo; end;
+        class Bar; end;
+
+        @api = Her::API.new
+        @api.setup :base_uri => "https://api.example.com" do |builder|
+          builder.use Foo
+          builder.insert 0, Bar
+        end
+        @api.connection.builder.handlers.should == [Bar, Her::Middleware::FirstLevelParseJSON, Faraday::Request::UrlEncoded, Faraday::Adapter::NetHttp, Foo]
+      end # }}}
+
+      it "delete some default middleware" do # {{{
+        @api = Her::API.new
+        @api.setup :base_uri => "https://api.example.com" do |builder|
+          builder.delete Faraday::Request::UrlEncoded
+        end
+        @api.connection.builder.handlers.should == [Her::Middleware::FirstLevelParseJSON, Faraday::Adapter::NetHttp]
+      end # }}}
     end
 
     describe "#request" do
       it "makes HTTP requests" do # {{{
         FakeWeb.register_uri(:get, "https://api.example.com/foo", :body => "Foo, it is.")
 
-        class Foo < Faraday::Response::Middleware
+        class SimpleParser < Faraday::Response::Middleware
           def on_complete(env)
             env[:body] = { :data => env[:body] }
           end
         end
 
         @api = Her::API.new
-        @api.setup :base_uri => "https://api.example.com", :parse_middleware => Foo
+        @api.setup :base_uri => "https://api.example.com", :parse_middleware => SimpleParser
         parsed_data = @api.request(:_method => :get, :_path => "/foo")
         parsed_data[:data] == "Foo, it is."
       end # }}}
@@ -63,8 +95,7 @@ describe Her::API do
 
         @api = Her::API.new
         @api.setup :base_uri => "https://api.example.com" do |connection|
-          connection.delete Her::Middleware::DefaultParseJSON
-          connection.use CustomParser
+          connection.swap Her::Middleware::DefaultParseJSON, CustomParser
         end
         parsed_data = @api.request(:_method => :get, :_path => "users/1")
         parsed_data[:data].should == { :id => 1, :name => "George Michael Bluth" }

data/spec/model/paths_spec.rb

@@ -3,38 +3,53 @@ require File.join(File.dirname(__FILE__), "../spec_helper.rb")
 
 describe Her::Model::Paths do
   context "building request paths" do
-    before do # {{{
-      spawn_model :User
-    end # }}}
-
-    describe "#build_request_path" do
-      it "builds paths with defaults" do # {{{
-        User.build_request_path(id: "foo").should == "/users/foo"
-        User.build_request_path.should == "/users"
-      end # }}}
-
-      it "builds paths with custom collection path" do # {{{
-        User.collection_path "/utilisateurs"
-        User.build_request_path(id: "foo").should == "/utilisateurs/foo"
-        User.build_request_path.should == "/utilisateurs"
+    context "simple model" do
+      before do # {{{
+        spawn_model :User
       end # }}}
 
-      it "builds paths with custom collection path with multiple variables" do # {{{
-        User.collection_path "/organizations/:organization_id/utilisateurs"
-        User.build_request_path(:id => "foo", :_organization_id => "acme").should == "/organizations/acme/utilisateurs/foo"
-        User.build_request_path(:_organization_id => "acme").should == "/organizations/acme/utilisateurs"
-      end # }}}
+      describe "#build_request_path" do
+        it "builds paths with defaults" do # {{{
+          User.build_request_path(id: "foo").should == "/users/foo"
+          User.build_request_path.should == "/users"
+        end # }}}
+
+        it "builds paths with custom collection path" do # {{{
+          User.collection_path "/utilisateurs"
+          User.build_request_path(id: "foo").should == "/utilisateurs/foo"
+          User.build_request_path.should == "/utilisateurs"
+        end # }}}
+
+        it "builds paths with custom collection path with multiple variables" do # {{{
+          User.collection_path "/organizations/:organization_id/utilisateurs"
+          User.build_request_path(:id => "foo", :_organization_id => "acme").should == "/organizations/acme/utilisateurs/foo"
+          User.build_request_path(:_organization_id => "acme").should == "/organizations/acme/utilisateurs"
+        end # }}}
+
+        it "builds paths with custom item path" do # {{{
+          User.resource_path "/utilisateurs/:id"
+          User.build_request_path(id: "foo").should == "/utilisateurs/foo"
+          User.build_request_path.should == "/users"
+        end # }}}
+
+        it "raises exceptions when building a path without required custom variables" do # {{{
+          User.collection_path "/organizations/:organization_id/utilisateurs"
+          expect { User.build_request_path(:id => "foo") }.should raise_error(Her::Errors::PathError)
+        end # }}}
+      end
+    end
 
-      it "builds paths with custom item path" do # {{{
-        User.resource_path "/utilisateurs/:id"
-        User.build_request_path(id: "foo").should == "/utilisateurs/foo"
-        User.build_request_path.should == "/users"
+    context "nested model" do
+      before do # {{{
+        spawn_submodel :Base, :User
       end # }}}
 
-      it "raises exceptions when building a path without required custom variables" do # {{{
-        User.collection_path "/organizations/:organization_id/utilisateurs"
-        expect { User.build_request_path(:id => "foo") }.should raise_error(Her::Errors::PathError)
-      end # }}}
+      describe "#build_request_path" do
+        it "builds paths with defaults" do # {{{
+          Base::User.build_request_path(id: "foo").should == "/users/foo"
+          Base::User.build_request_path.should == "/users"
+        end # }}}
+      end
     end
   end
 

data/spec/spec_helper.rb

@@ -19,8 +19,13 @@ class Array
   def to_json; MultiJson.dump(self); end
 end
 
-def spawn_model(klass, attrs={}, &block)
+def spawn_model(klass, &block)
   Object.instance_eval { remove_const klass } if Object.const_defined?(klass)
   Object.const_set(klass, Class.new).send(:include, Her::Model)
   Object.const_get(klass).class_eval(&block) if block_given?
 end
+
+def spawn_submodel(mod, klass)
+  Object.instance_eval { remove_const mod } if Object.const_defined?(mod)
+  Object.const_set(mod, Module.new).const_set(klass, Class.new).send(:include, Her::Model)
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: her
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-30 00:00:00.000000000Z
+date: 2012-05-01 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -281,7 +281,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 453966821948784652
+      hash: -2369072493348034064
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -290,7 +290,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 453966821948784652
+      hash: -2369072493348034064
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.18