her 0.0.1 → 0.1

data/.travis.yml

@@ -0,0 +1,2 @@
+rvm: 1.9.2
+script: "bundle exec rake spec"

data/README.md

@@ -8,29 +8,55 @@ Her is an ORM (Object Relational Mapper) that maps REST resources to Ruby object
 
 In your Gemfile, add:
 
-    gem "her"
+```ruby
+gem "her"
+```
+
+That’s it!
 
 ## Usage
 
-To add the ORM to a class, you just have to include `Her::Model` in it and define which API you want it to be bound to. For example, with Rails, you would define a `config/initializers/her.rb` file with this:
+First, you have to define which API your models will be bound to. For example, with Rails, you would create a new `config/initializers/her.rb` file with this line:
 
 ```ruby
-$my_api = Her::API.new
-$my_api.setup :base_uri => "https://api.example.com"
+Her::API.setup :base_uri => "https://api.example.com"
 ```
 
-And then, for each of your models:
+And then to add the ORM behavior to a class, you just have to include `Her::Model` in it:
 
 ```ruby
 class User
   include Her::Model
-  uses_api $my_api
 end
 ```
 
 After that, using Her is very similar to many ActiveModel-like ORMs:
 
 ```ruby
-User.all     # => Fetches "https://api.example.com/users" and return an array of User objects
-User.find(1) # => Fetches "https://api.example.com/users/1" and return a User object
+User.all      # => Fetches "https://api.example.com/users" and return an array of User objects
+User.find(1)  # => Fetches "https://api.example.com/users/1" and return a User object
+```
+
+## Relationships
+
+```ruby
+class User
+  include Her::Model
+  has_many :comments
+end
+
+class Comment
+  include Her::Model
+end
+
+user = User.find(1)
+user.comments # => [#<Comment id=1>, #<Comment id=2>]
 ```
+
+## Custom requests
+
+TBD.
+
+## Hooks
+
+TBD.

data/lib/her/api.rb

@@ -9,6 +9,17 @@ module Her
     # @private
     attr_reader :base_uri, :parse_with
 
+    # Setup a default API connection
+    def self.setup(attrs={}) # {{{
+      @@default_api = new
+      @@default_api.setup(attrs)
+    end # }}}
+
+    # @private
+    def self.default_api(attrs={}) # {{{
+      defined?(@@default_api) ? @@default_api : nil
+    end # }}}
+
     # Setup the API connection
     def setup(attrs={}) # {{{
       @base_uri = attrs[:base_uri]
@@ -21,13 +32,13 @@ module Her
         }
       end
       @connection = Faraday.new(:url => @base_uri) do |builder|
-        builder.request  :url_encoded
-        builder.adapter  :net_http
+        builder.request :url_encoded
+        builder.adapter :net_http
       end
     end # }}}
 
     # Define a custom parsing procedure. The procedure is passed the response object and is
-    # expected to return hash with three keys: a main resource Hash, an errors Array
+    # expected to return a hash with three keys: a main resource Hash, an errors Array
     # and a metadata Hash.
     #
     # @example
@@ -47,8 +58,18 @@ module Her
 
     # Make an HTTP request to the API
     def request(attrs={}) # {{{
-      # TODO Here, we would probably look for hooks that modify the request before calling the API
-      @connection.send(attrs[:method], attrs[:path])
+      method = attrs.delete(:_method)
+      path = attrs.delete(:_path)
+      @connection.send method do |request|
+        if method == :get
+          # For GET requests, treat additional parameters as querystring data
+          request.url path, attrs
+        else
+          # For POST, PUT and DELETE requests, treat additional parameters as request body
+          request.url path
+          request.body = attrs
+        end
+      end
     end # }}}
 
     # Parse the HTTP response

data/lib/her/model.rb

@@ -22,11 +22,14 @@ module Her
 
     # Class methods
     included do
-      @her_collection_path = "#{self.to_s.downcase.pluralize}"
       extend Her::Model::Base
       extend Her::Model::HTTP
       extend Her::Model::ORM
       extend Her::Model::Relationships
+
+      # Define default settings
+      collection_path "#{self.to_s.downcase.pluralize}"
+      uses_api Her::API.default_api
     end
   end
 end

data/lib/her/model/http.rb

@@ -27,12 +27,36 @@ module Her
         yield @her_api.parse(response)
       end # }}}
 
-      # Make a GET request and return the parsed JSON response
+      # Make a GET request and return the parsed JSON response (not mapped to objects)
       #
       # @example
-      #   User.get "/users/foo"
+      #   User.get "/users/1"
       def get(path, attrs={}, &block) # {{{
-        request(attrs.merge(:method => :get, :path => path), &block)
+        request(attrs.merge(:_method => :get, :_path => path), &block)
+      end # }}}
+
+      # Make a POST request and return the parsed JSON response (not mapped to objects)
+      #
+      # @example
+      #   User.post "/users", :fullname => "G.O.B. Bluth"
+      def post(path, attrs={}, &block) # {{{
+        request(attrs.merge(:_method => :post, :_path => path), &block)
+      end # }}}
+
+      # Make a PUT request and return the parsed JSON response (not mapped to objects)
+      #
+      # @example
+      #   User.put "/users/1", :email => "gob@bluthcompany.com"
+      def put(path, attrs={}, &block) # {{{
+        request(attrs.merge(:_method => :put, :_path => path), &block)
+      end # }}}
+
+      # Make a DELETE request and return the parsed JSON response (not mapped to objects)
+      #
+      # @example
+      #   User.delete "/users/1"
+      def delete(path, attrs={}, &block) # {{{
+        request(attrs.merge(:_method => :delete, :_path => path), &block)
       end # }}}
     end
   end

data/lib/her/model/orm.rb

@@ -23,18 +23,25 @@ module Her
       end # }}}
 
       # Fetch a specific resource based on an ID
-      def find(id) # {{{
-        request(:method => :get, :path => "#{@her_collection_path}/#{id}") do |parsed_data|
+      def find(id, params={}) # {{{
+        request(params.merge(:_method => :get, :_path => "#{@her_collection_path}/#{id}")) do |parsed_data|
           new(parsed_data[:resource])
         end
       end # }}}
 
       # Fetch a collection of resources
       def all(params={}) # {{{
-        request(:method => :get, :path => "#{@her_collection_path}") do |parsed_data|
+        request(params.merge(:_method => :get, :_path => "#{@her_collection_path}")) do |parsed_data|
           Her::Model::ORM.initialize_collection(to_s.downcase.pluralize, parsed_data[:resource])
         end
       end # }}}
+
+      # Create a resource
+      def create(params={}) # {{{
+        request(params.merge(:_method => :post, :_path => "#{@her_collection_path}")) do |parsed_data|
+          new(parsed_data[:resource])
+        end
+      end # }}}
     end
   end
 end

data/lib/her/version.rb

@@ -1,3 +1,3 @@
 module Her
-  VERSION = "0.0.1"
+  VERSION = "0.1"
 end

data/spec/api_spec.rb

@@ -3,6 +3,13 @@ require File.join(File.dirname(__FILE__), "spec_helper.rb")
 
 describe Her::API do
   context "initialization" do
+    describe ".setup" do
+      it "creates a default connection" do # {{{
+        Her::API.setup :base_uri => "https://api.example.com"
+        Her::API.default_api.base_uri.should == "https://api.example.com"
+      end # }}}
+    end
+
     describe "#setup" do
       it "sets a base URI" do # {{{
         @api = Her::API.new
@@ -28,7 +35,7 @@ describe Her::API do
       end # }}}
 
       it "makes HTTP requests" do # {{{
-        response = @api.request(:method => :get, :path => "/foo")
+        response = @api.request(:_method => :get, :_path => "/foo")
         response.body.should == "Foo, it is."
       end # }}}
     end
@@ -41,7 +48,7 @@ describe Her::API do
       end # }}}
 
       it "parses a request" do # {{{
-        @api.parse @api.request(:method => :get, :path => "users/1") do |parsed_data|
+        @api.parse @api.request(:_method => :get, :_path => "users/1") do |parsed_data|
           parsed_data[:resource].should == { :id => 1, :name => "George Michael Bluth" }
           parsed_data[:errors].should == ["This is a single error"]
           parsed_data[:metadata].should == { :page => 1, :per_page => 10 }

data/spec/model_spec.rb

@@ -2,6 +2,133 @@
 require File.join(File.dirname(__FILE__), "spec_helper.rb")
 
 describe Her::Model do
+  describe Her::Model::HTTP do
+    context "binding a model with an API" do # {{{
+      it "binds a model to an instance of Her::API" do # {{{
+        @api = Her::API.new
+        @api.setup :base_uri => "https://api.example.com"
+
+        Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
+        class User
+          include Her::Model
+        end
+        User.uses_api @api
+
+        User.class_eval do
+          @her_api.should_not == nil
+          @her_api.base_uri.should == "https://api.example.com"
+        end
+      end # }}}
+
+      it "binds a model directly to Her::API" do # {{{
+        Her::API.setup :base_uri => "https://api.example.com"
+
+        Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
+        class User
+          include Her::Model
+        end
+
+        User.class_eval do
+          @her_api.should_not == nil
+          @her_api.base_uri.should == "https://api.example.com"
+        end
+      end # }}}
+
+      it "binds two models to two different instances of Her::API" do # {{{
+        @api1 = Her::API.new
+        @api1.setup :base_uri => "https://api1.example.com"
+
+        Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
+        class User; include Her::Model; end
+        User.uses_api @api1
+
+        User.class_eval do
+          @her_api.base_uri.should == "https://api1.example.com"
+        end
+
+        @api2 = Her::API.new
+        @api2.setup :base_uri => "https://api2.example.com"
+
+        Object.instance_eval { remove_const :Comment } if Object.const_defined?(:Comment)
+        class Comment; include Her::Model; end
+        Comment.uses_api @api2
+
+        Comment.class_eval do
+          @her_api.base_uri.should == "https://api2.example.com"
+        end
+      end # }}}
+
+      it "binds one model to Her::API and another one to an instance of Her::API" do # {{{
+        Her::API.setup :base_uri => "https://api1.example.com"
+        Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
+        class User; include Her::Model; end
+
+        User.class_eval do
+          @her_api.base_uri.should == "https://api1.example.com"
+        end
+
+        @api = Her::API.new
+        @api.setup :base_uri => "https://api2.example.com"
+
+        Object.instance_eval { remove_const :Comment } if Object.const_defined?(:Comment)
+        class Comment; include Her::Model; end
+        Comment.uses_api @api
+
+        Comment.class_eval do
+          @her_api.base_uri.should == "https://api2.example.com"
+        end
+      end # }}}
+    end # }}}
+
+    context "making HTTP requests" do
+      before do # {{{
+        @api = Her::API.new
+        @api.setup :base_uri => "https://api.example.com"
+        FakeWeb.register_uri(:get, "https://api.example.com/users", :body => { :data => [{ :id => 1 }] }.to_json)
+        FakeWeb.register_uri(:get, "https://api.example.com/users?page=2", :body => { :data => [{ :id => 2 }] }.to_json)
+        FakeWeb.register_uri(:post, "https://api.example.com/users", :body => { :data => [{ :id => 3 }] }.to_json)
+        FakeWeb.register_uri(:put, "https://api.example.com/users/4", :body => { :data => [{ :id => 4 }] }.to_json)
+        FakeWeb.register_uri(:delete, "https://api.example.com/users/5", :body => { :data => [{ :id => 5 }] }.to_json)
+
+        Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
+        class User
+          include Her::Model
+        end
+        User.uses_api @api
+      end # }}}
+
+      it "handle GET" do # {{{
+        User.get("/users") do |parsed_data|
+          parsed_data[:resource].should == [{ :id => 1 }]
+        end
+      end # }}}
+
+      it "handle POST" do # {{{
+        User.post("/users") do |parsed_data|
+          parsed_data[:resource].should == [{ :id => 3 }]
+        end
+      end # }}}
+
+      it "handle PUT" do # {{{
+        User.put("/users/4") do |parsed_data|
+          parsed_data[:resource].should == [{ :id => 4 }]
+        end
+      end # }}}
+
+      it "handle DELETE" do # {{{
+        User.delete("/users/5") do |parsed_data|
+          parsed_data[:resource].should == [{ :id => 5 }]
+        end
+      end # }}}
+
+      it "handle querystring parameters" do # {{{
+        User.get("/users", :page => 2) do |parsed_data|
+          parsed_data[:resource].should == [{ :id => 2 }]
+        end
+      end # }}}
+    end
+  end
+
   describe Her::Model::ORM do
     context "mapping data to Ruby objects" do # {{{
       before do # {{{
@@ -29,10 +156,24 @@ describe Her::Model do
         @users.first.name.should == "Tobias Fünke"
       end # }}}
     end # }}}
+
+    context "creating resources" do
+      before do # {{{
+        @api = Her::API.new
+        @api.setup :base_uri => "https://api.example.com"
+        FakeWeb.register_uri(:post, "https://api.example.com/users", :body => { :data => { :id => 1, :fullname => "Tobias Fünke" } }.to_json)
+      end # }}}
+
+      it "handle one-line resource creation" do # {{{
+        @user = User.create(:fullname => "Tobias Fünke")
+        @user.id.should == 1
+        @user.fullname.should == "Tobias Fünke"
+      end # }}}
+    end
   end
 
   describe Her::Model::Relationships do
-    context "setting associations" do # {{{
+    context "setting relationships" do # {{{
       before do # {{{
         Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
         class User
@@ -40,27 +181,62 @@ describe Her::Model do
         end
       end # }}}
 
-      it "handles a single 'has_many' association" do # {{{
+      it "handles a single 'has_many' relationship" do # {{{
         User.has_many :comments
         User.relationships[:has_many].should == [{ :name => :comments }]
       end # }}}
 
-      it "handles multiples 'has_many' associations" do # {{{
+      it "handles multiples 'has_many' relationship" do # {{{
         User.has_many :comments
         User.has_many :posts
         User.relationships[:has_many].should == [{ :name => :comments }, { :name => :posts }]
       end # }}}
 
-      it "handles a single belongs_to association" do # {{{
+      it "handles a single belongs_to relationship" do # {{{
         User.belongs_to :organization
         User.relationships[:belongs_to].should == [{ :name => :organization }]
       end # }}}
 
-      it "handles multiples 'belongs_to' associations" do # {{{
+      it "handles multiples 'belongs_to' relationship" do # {{{
         User.belongs_to :organization
         User.belongs_to :family
         User.relationships[:belongs_to].should == [{ :name => :organization }, { :name => :family }]
       end # }}}
     end # }}}
+
+    context "handling relationships" do # {{{
+      before do # {{{
+        Her::API.setup :base_uri => "https://api.example.com"
+        FakeWeb.register_uri(:get, "https://api.example.com/users/1", :body => { :data => { :id => 1, :name => "Tobias Fünke", :comments => [{ :id => 2, :body => "Tobias, you blow hard!" }, { :id => 3, :body => "I wouldn't mind kissing that man between the cheeks, so to speak" }] } }.to_json)
+        FakeWeb.register_uri(:get, "https://api.example.com/users/2", :body => { :data => { :id => 2, :name => "Lindsay Fünke" } }.to_json)
+        FakeWeb.register_uri(:get, "https://api.example.com/users/2/comments", :body => { :data => [{ :id => 4, :body => "They're having a FIRESALE?" }, { :id => 5, :body => "Is this the tiny town from Footloose?" }] }.to_json)
+
+        Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
+        class User
+          include Her::Model
+          has_many :comments
+        end
+
+        Object.instance_eval { remove_const :Comment } if Object.const_defined?(:Comment)
+        class Comment
+          include Her::Model
+        end
+      end # }}}
+
+      it "maps an array of included data" do # {{{
+        @user = User.find(1)
+        @user.comments.length.should == 2
+        @user.comments.first.id.should == 2
+        @user.comments.first.body.should == "Tobias, you blow hard!"
+      end # }}}
+
+      it "fetches data that was not included" do # {{{
+        @user = User.find(2)
+        @user.comments.length.should == 2
+        @user.comments.first.id.should == 4
+        @user.comments.first.body.should == "They're having a FIRESALE?"
+      end # }}}
+
+    end # }}}
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: her
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: '0.1'
   prerelease: 
 platform: ruby
 authors:
@@ -163,6 +163,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - README.md
 - Rakefile
@@ -192,7 +193,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1076475942848490039
+      hash: -4283356893528248236
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -201,7 +202,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1076475942848490039
+      hash: -4283356893528248236
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.18