her 0.1.1 → 0.1.5

data/LICENSE

@@ -0,0 +1,3 @@
+Copyright 2012 Rémi Prévost.
+You may use this work without restrictions, as long as this notice is included.
+The work is provided "as is" without warranty of any kind, neither express nor implied.

data/README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://secure.travis-ci.org/remiprev/her.png)](http://travis-ci.org/remiprev/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.
+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.
 
 ## Installation
 
@@ -19,6 +19,7 @@ That’s it!
 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
+# config/initializers/her.rb
 Her::API.setup :base_uri => "https://api.example.com"
 ```
 
@@ -33,15 +34,82 @@ 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
+# GET https://api.example.com/users and return an array of User objects
+
+User.find(1)
+# GET https://api.example.com/users/1 and return a User object
+
+@user = User.create(:fullname => "Tobias Fünke")
+# POST "https://api.example.com/users" with the data and return a User object
+
+@user = User.new(:fullname => "Tobias Fünke")
+@user.occupation = "actor"
+@user.save
+# POST https://api.example.com/users with the data and return a User object
+
+@user = User.find(1)
+@user.fullname = "Lindsay Fünke"
+@user.save
+# PUT https://api.example.com/users/1 with the data and return+update the User object
+```
+
+## Parsing data
+
+By default, Her handles JSON data. It expects the data to be formatted in a certain structure. The default is this:
+
+```javascript
+// The response of GET /users/1
+{
+  "data" : {
+    "id" : 1,
+    "name" : "Tobias Fünke"
+  }
+}
+
+// The response of GET /users
+{
+  "data" : [
+    {
+      "id" : 1,
+      "name" : "Tobias Fünke"
+    },
+    {
+      "id" : 2,
+      "name" : "Lindsay Fünke"
+    }
+  ],
+  "metadata" : {
+    "page" : 1,
+    "per_page" : 10
+  }
+}
+```
+
+However, you can define your own parsing method, with `Her::API.parse_with`. The `parse_with` method takes a block which will be executed each time data from an HTTP response needs to be parsed. The block is expected to return a hash with three keys: `data`, `errors` and `metadata`. The following code enables parsing JSON data and treating this data as first-level properties:
+
+```ruby
+Her::API.setup :base_uri => "https://api.example.com"
+Her::API.parse_with |response|
+  json = JSON.parse(response.body, :symbolize_names => true)
+  errors = json.delete(:errors)
+  {
+    :data => json,
+    :errors => errors || [],
+    :metadata => {}
+  }
+end
+
+# User.find(1) will now expect "https://api.example.com/users/1" to return something like '{ "id": 1, "name": "Tobias Fünke" }'
 ```
 
+This feature is not stable and might change in the future, probably by using a middleware through [Faraday](https://github.com/technoweenie/faraday).
+
 ## Relationships
 
-You can define `has_many` 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. When parsing a resource from JSON data, if there’s a relationship data included, 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).
+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).
 
 For example, with this setup:
 
@@ -49,32 +117,58 @@ For example, with this setup:
 class User
   include Her::Model
   has_many :comments
+  has_one :role
+  belongs_to :organization
 end
 
 class Comment
   include Her::Model
 end
+
+class Role
+  include Her::Model
+end
+
+class Organization
+  include Her::Model
+end
 ```
 
-Including relationship data in the resource, no extra HTTP request is made when calling the `#comments` method:
+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:
 
 ```ruby
-@user = User.find(1) # { :data => { :id => 1, :name => "Rémi Prévost", :comments => [{ :id => 1, :text => "Foo" }, { :id => 2, :text => "Bar" }] }}
+@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" } }}
 @user.comments # => [#<Comment id=1>, #<Comment id=2>] fetched directly from @user
+@user.role # => #<Role id=1> fetched directly from @user
+@user.organization # => #<Organization id=2> fetched directly from @user
 ```
 
 If there’s no relationship data in the resource, an extra HTTP request (to `GET /users/1/comments`) is made when calling the `#comments` method:
 
 ```ruby
-@user = User.find(1) # { :data => { :id => 1, :name => "Rémi Prévost" }}
+@user = User.find(1) # { :data => { :id => 1, :name => "George Michael Bluth" }}
 @user.comments # => [#<Comment id=1>, #<Comment id=2>] fetched from /users/1/comments
 ```
 
-However, subsequent calls to `#comments` will not trigger the extra HTTP request.
+For `has_one` relationship, 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:
+
+```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.
 
 ## Custom requests
 
-You can easily add custom methods for your models. You can either use `get_collection` (which maps the returned data to a collection of resources), `get_resource` (which maps the returned data to a single resource) or `get_raw` (which yields the parsed data return from the HTTP request).
+You can easily add custom methods for your models. You can either use `get_collection` (which maps the returned data to a collection of resources), `get_resource` (which maps the returned data to a single resource) or `get_raw` (which yields the parsed data return from the HTTP request). Other HTTP methods are supported (`post_raw`, `put_resource`, etc.)
 
 ```ruby
 class User
@@ -94,3 +188,55 @@ end
 User.popular  # => [#<User id=1>, #<User id=2>]
 User.total    # => 42
 ```
+
+## Multiple APIs
+
+It is possible to use different APIs for different models. Instead of calling `Her::API.setup`, you can create instances of `Her::API`:
+
+```ruby
+# config/initializers/her.rb
+$my_api = Her::API.new
+$my_api.setup :base_uri => "https://my_api.example.com"
+
+$other_api = Her::API.new
+$other_api.setup :base_uri => "https://other_api.example.com"
+```
+
+You can then define which API a model will use:
+
+```ruby
+class User
+  include Her::Model
+  uses_api $my_api
+end
+
+class Category
+  include Her::Model
+  uses_api $other_api
+end
+
+User.all
+# GET https://my_api.example.com/users
+
+Category.all
+# GET https://other_api.example.com/categories
+```
+
+## Things to be done
+
+* Deleting resources
+* Support for Faraday middleware to handle caching, alternative formats, etc.
+* Hooks before save, update, create, destroy, etc.
+* Better error handling
+* Better introspection for debug
+* Better documentation
+
+## Contributors
+
+Feel free to contribute and submit issues/pull requests [on GitHub](https://github.com/remiprev/her/issues).
+
+Take a look at the `spec` folder before you do, and make sure `bundle exec rake spec` passes after your modifications :)
+
+## License
+
+Her is © 2012 [Rémi Prévost](http://exomel.com) and may be freely distributed under the [LITL license](https://github.com/remiprev/her/blob/master/LICENSE). See the `LICENSE` file.

data/lib/her/model.rb

@@ -29,6 +29,7 @@ module Her
 
       # Define default settings
       collection_path "#{self.to_s.downcase.pluralize}"
+      item_path "#{self.to_s.downcase}"
       uses_api Her::API.default_api
     end
   end

data/lib/her/model/http.rb

@@ -19,6 +19,18 @@ module Her
         @her_collection_path = path
       end # }}}
 
+      # Defines a custom item path for the resource
+      #
+      # @example
+      #  class User
+      #    include Her::Model
+      #    item_path "user"
+      #  end
+      def item_path(path=nil) # {{{
+        return @her_item_path unless path
+        @her_item_path = path
+      end # }}}
+
       # Main request wrapper around Her::API. Used to make custom request to the API.
       # @private
       def request(attrs={}, &block) # {{{

data/lib/her/model/orm.rb

@@ -9,15 +9,6 @@ module Her
         @data = self.class.parse_relationships(@data)
       end # }}}
 
-      # Initialize a collection of resources with raw data from an HTTP request
-      #
-      # @example
-      #   User.get("/users/popular") { |data| User.new_collection(data) }
-      def new_collection(parsed_data) # {{{
-        collection_data = parsed_data[:data]
-        Her::Model::ORM.initialize_collection(self.to_s.downcase.to_sym, collection_data)
-      end # }}}
-
       # Initialize a collection of resources
       # @private
       def self.initialize_collection(name, collection_data) # {{{
@@ -40,6 +31,12 @@ module Her
         end
       end # }}}
 
+      # Initialize a collection of resources with raw data from an HTTP request
+      def new_collection(parsed_data) # {{{
+        collection_data = parsed_data[:data]
+        Her::Model::ORM.initialize_collection(self.to_s.downcase.to_sym, collection_data)
+      end # }}}
+
       # Fetch a specific resource based on an ID
       def find(id, params={}) # {{{
         request(params.merge(:_method => :get, :_path => "#{@her_collection_path}/#{id}")) do |parsed_data|
@@ -50,7 +47,7 @@ module Her
       # Fetch a collection of resources
       def all(params={}) # {{{
         request(params.merge(:_method => :get, :_path => "#{@her_collection_path}")) do |parsed_data|
-          Her::Model::ORM.initialize_collection(to_s.downcase.pluralize, parsed_data[:data])
+          new_collection(parsed_data)
         end
       end # }}}
 

data/lib/her/model/relationships.rb

@@ -14,7 +14,15 @@ module Her
         @her_relationships ||= {}
         @her_relationships.each_pair do |type, relationships|
           relationships.each do |relationship|
-            data[relationship[:name]] = Her::Model::ORM.initialize_collection(relationship[:name], data[relationship[:name]]) if data.include?(relationship[:name])
+            if data.include?(relationship[:name])
+              if type == :has_many
+                data[relationship[:name]] = Her::Model::ORM.initialize_collection(relationship[:name], data[relationship[:name]])
+              elsif type == :has_one
+                data[relationship[:name]] = Object.const_get(relationship[:name].to_s.classify).new(data[relationship[:name]])
+              elsif type == :belongs_to
+                data[relationship[:name]] = Object.const_get(relationship[:name].to_s.classify).new(data[relationship[:name]])
+              end
+            end
           end
         end
         data
@@ -24,9 +32,9 @@ module Her
       #
       # * `User.has_many :comments` is used to check if the "user" JSON
       #   resource we receive has a `comments` key and map it to an array
-      #   of Comment.new objects
+      #   of Comment objects
       # * `User.has_many :comments` creates a User.comments method to would
-      #   make an extra HTTP request if there was no "comments" key
+      #   make an extra HTTP request (to `/users/:id/comments`) if there was no "comments" key
       def has_many(name, attrs={}) # {{{
         @her_relationships ||= {}
         (@her_relationships[:has_many] ||= []) << attrs.merge(:name => name)
@@ -38,18 +46,38 @@ module Her
         end
       end # }}}
 
-      # Define a *belongs_to* relationship for the resource
+      # Define an *has_one* relationship for the resource
       #
-      # * `User.belongs_to :organzation` is used to check if the "user" JSON
-      #   resource we receive has an `organzation` key and map it to
-      #   an Organization.new object
+      # * `User.has_one :category` is used to check if the "category" JSON
+      #   resource we receive has a `category` key and map it to a Category object
+      # * `User.has_one :category` creates a User.category method to would
+      #   make an extra HTTP request (to `/users/category`) if there was no "category" key
+      def has_one(name, attrs={}) # {{{
+        @her_relationships ||= {}
+        (@her_relationships[:has_one] ||= []) << attrs.merge(:name => name)
+        collection_path = @her_collection_path
+
+        define_method(name) do
+          return @data[name] if @data.include?(name) # Do not fetch from API again if we have it in @data
+          self.class.get_resource("#{collection_path}/#{id}/#{Object.const_get(name.to_s.classify).item_path}")
+        end
+      end # }}}
+
+      # Define a *belongs_to* relationship for the resource
       #
-      # * `User.belongs_to :organzation` creates a User.organzation method
+      # * `User.belongs_to :organization` is used to check if the "organization" JSON
+      #   resource we receive has a `organization` key and map it to an Organization object
+      # * `User.belongs_to :organization` creates a User.organization method to would
+      #   make an extra HTTP request (to `/organizations/:organization_id`) if there was no "organization" key
       def belongs_to(name, attrs={}) # {{{
         @her_relationships ||= {}
         (@her_relationships[:belongs_to] ||= []) << attrs.merge(:name => name)
+        collection_path = @her_collection_path
 
-        # TODO Write some code here
+        define_method(name) do
+          return @data[name] if @data.include?(name) # Do not fetch from API again if we have it in @data
+          self.class.get_resource("#{Object.const_get(name.to_s.classify).collection_path}/#{@data["#{name}_id".to_sym]}")
+        end
       end # }}}
     end
   end

data/lib/her/version.rb

@@ -1,3 +1,3 @@
 module Her
-  VERSION = "0.1.1"
+  VERSION = "0.1.5"
 end

data/spec/model_spec.rb

@@ -214,12 +214,12 @@ describe Her::Model do
         end
       end # }}}
 
-      it "handle resource data update without saving it" do
+      it "handle resource data update without saving it" do # {{{
         @user = User.find(1)
         @user.fullname.should == "Tobias Fünke"
         @user.fullname = "Kittie Sanchez"
         @user.fullname.should == "Kittie Sanchez"
-      end
+      end # }}}
 
       it "handle resource update through #save on an existing resource" do # {{{
         @user = User.find(1)
@@ -250,6 +250,17 @@ describe Her::Model do
         User.relationships[:has_many].should == [{ :name => :comments }, { :name => :posts }]
       end # }}}
 
+      it "handles a single 'has_one' relationship" do # {{{
+        User.has_one :category
+        User.relationships[:has_one].should == [{ :name => :category }]
+      end # }}}
+
+      it "handles multiples 'has_one' relationship" do # {{{
+        User.has_one :category
+        User.has_one :role
+        User.relationships[:has_one].should == [{ :name => :category }, { :name => :role }]
+      end # }}}
+
       it "handles a single belongs_to relationship" do # {{{
         User.belongs_to :organization
         User.relationships[:belongs_to].should == [{ :name => :organization }]
@@ -265,20 +276,34 @@ describe Her::Model do
     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/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" }], :role => { :id => 1, :body => "Admin" }, :organization => { :id => 1, :name => "Bluth Company" }, :organization_id => 1 } }.to_json)
+        FakeWeb.register_uri(:get, "https://api.example.com/users/2", :body => { :data => { :id => 2, :name => "Lindsay Fünke", :organization_id => 1 } }.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)
+        FakeWeb.register_uri(:get, "https://api.example.com/users/2/role", :body => { :data => { :id => 2, :body => "User" } }.to_json)
+        FakeWeb.register_uri(:get, "https://api.example.com/organizations/1", :body => { :data => { :id => 1, :name => "Bluth Company" } }.to_json)
 
         Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
         class User
           include Her::Model
           has_many :comments
+          has_one :role
+          belongs_to :organization
+        end
+
+        Object.instance_eval { remove_const :Organization } if Object.const_defined?(:Organization)
+        class Organization
+          include Her::Model
         end
 
         Object.instance_eval { remove_const :Comment } if Object.const_defined?(:Comment)
         class Comment
           include Her::Model
         end
+
+        Object.instance_eval { remove_const :Role } if Object.const_defined?(:Role)
+        class Role
+          include Her::Model
+        end
       end # }}}
 
       it "maps an array of included data" do # {{{
@@ -286,6 +311,12 @@ describe Her::Model do
         @user.comments.length.should == 2
         @user.comments.first.id.should == 2
         @user.comments.first.body.should == "Tobias, you blow hard!"
+
+        @user.role.id.should == 1
+        @user.role.body.should == "Admin"
+
+        @user.organization.id.should == 1
+        @user.organization.name.should == "Bluth Company"
       end # }}}
 
       it "fetches data that was not included" do # {{{
@@ -293,6 +324,12 @@ describe Her::Model do
         @user.comments.length.should == 2
         @user.comments.first.id.should == 4
         @user.comments.first.body.should == "They're having a FIRESALE?"
+
+        @user.role.id.should == 2
+        @user.role.body.should == "User"
+
+        @user.organization.id.should == 1
+        @user.organization.name.should == "Bluth Company"
       end # }}}
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: her
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-09 00:00:00.000000000Z
+date: 2012-04-11 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -165,6 +165,7 @@ files:
 - .gitignore
 - .travis.yml
 - Gemfile
+- LICENSE
 - README.md
 - Rakefile
 - her.gemspec
@@ -193,7 +194,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3007322587400233058
+      hash: -4167601811325738400
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -202,7 +203,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3007322587400233058
+      hash: -4167601811325738400
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.18