her 0.1.7 → 0.1.8

data/LICENSE

@@ -1,3 +1,7 @@
-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.
+Copyright (c) 2012 Rémi Prévost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -54,39 +54,40 @@ User.find(1)
 # PUT https://api.example.com/users/1 with the data and return+update the User object
 ```
 
-## Parsing data
+## 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.
+
+### Authentication
+
+Her doesn’t support any kind of authentication. However, it’s very easy to implement one with a request middleware. Using the `add_middleware` key, we add it to the default list of middleware.
+
+```ruby
+class MyAuthentication < Faraday::Middleware
+  def call(env)
+    env[:request_headers]["X-API-Token"] = "bb2b2dd75413d32c1ac421d39e95b978d1819ff611f68fc2fdd5c8b9c7331192"
+    @all.call(env)
+  end
+end
+
+Her::API.setup :base_uri => "https://api.example.com", :add_middleware => [MyAuthentication]
+```
+
+Now, each HTTP request made by Her will have the `X-API-Token` header.
+
+### 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"
-  }
-}
+{ "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
-  }
-}
+{ "data" : [{ "id" : 1, "name" : "Tobias Fünke" }] }
 ```
 
-However, you can define your own parsing method, using a Faraday response middleware. The middleware 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:
+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 `parse_middleware` key, we then replace the default parser.
 
 ```ruby
 class MyCustomParser < Faraday::Response::Middleware
@@ -94,16 +95,11 @@ class MyCustomParser < Faraday::Response::Middleware
     json = JSON.parse(env[:body], :symbolize_names => true)
     errors = json.delete(:errors) || []
     metadata = json.delete(:metadata) || []
-    env[:body] = {
-      :data => json,
-      :errors => errors,
-      :metadata => metadata,
-    }
+    env[:body] = { :data => json, :errors => errors, :metadata => metadata }
   end
 end
-Her::API.setup :base_uri => "https://api.example.com", :middleware => [MyCustomParser] + Her::API.default_middleware
-end
 
+Her::API.setup :base_uri => "https://api.example.com", :parse_middleware => MyCustomParser
 # User.find(1) will now expect "https://api.example.com/users/1" to return something like '{ "id": 1, "name": "Tobias Fünke" }'
 ```
 
@@ -190,25 +186,69 @@ In the future, adding hooks to all models will be possible, as well as defining
 
 ## 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). Other HTTP methods are supported (`post_raw`, `put_resource`, etc.)
+You can easily define custom requests for your models using `custom_get`, `custom_post`, etc.
+
+```ruby
+class User
+  include Her::Model
+  custom_get :popular, :unpopular
+  custom_post :from_default
+end
+
+User.popular # => [#<User id=1>, #<User id=2>]
+# GET /users/popular
+
+User.unpopular # => [#<User id=3>, #<User id=4>]
+# GET /users/unpopular
+
+User.from_default(:name => "Maeby Fünke") # => #<User id=5>
+# POST /users/from_default?name=Maeby+Fünke
+```
+
+You can also use `get`, `post`, `put` or `delete` (which maps the returned data to either a collection or a resource).
+
+```ruby
+class User
+  include Her::Model
+end
+
+User.get(:popular) # => [#<User id=1>, #<User id=2>]
+# GET /users/popular
+
+User.get(:single_best) # => #<User id=1>
+# GET /users/single_best
+```
+
+Also, `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) can also be used. Other HTTP methods are supported (`post_raw`, `put_resource`, etc.).
 
 ```ruby
 class User
   include Her::Model
 
   def self.popular
-    get_collection("/users/popular")
+    get_collection(:popular)
   end
 
   def self.total
-    get_raw("/users/stats") do |parsed_data|
+    get_raw(:stats) do |parsed_data|
       parsed_data[:data][:total_users]
     end
   end
 end
 
-User.popular  # => [#<User id=1>, #<User id=2>]
-User.total    # => 42
+User.popular # => [#<User id=1>, #<User id=2>]
+User.total # => 42
+```
+
+You can also use full request paths (with strings instead of symbols).
+
+```ruby
+class User
+  include Her::Model
+end
+
+User.get("/users/popular") # => [#<User id=1>, #<User id=2>]
+# GET /users/popular
 ```
 
 ## Multiple APIs
@@ -246,15 +286,17 @@ Category.all
 
 ## Things to be done
 
-* Support for Faraday middleware to handle caching, alternative formats, etc.
-* Hooks before save, update, create, destroy, etc.
+* Add support for collection paths of nested resources (eg. `/users/:user_id/comments` for the `Comment` model)
 * 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).
+Feel free to contribute and submit issues/pull requests [on GitHub](https://github.com/remiprev/her/issues) like these fine folks did:
+
+* [@jfcixmedia](https://github.com/jfcixmedia)
+* [@EtienneLem](https://github.com/EtienneLem)
+* [@rafaelss](https://github.com/rafaelss)
 
 Take a look at the `spec` folder before you do, and make sure `bundle exec rake spec` passes after your modifications :)
 

data/Rakefile

@@ -18,7 +18,7 @@ YARD::Rake::YardocTask.new do |task| # {{{
     "-o", File.expand_path("../doc", __FILE__),
     "--readme=README.md",
     "--markup=markdown",
-    "--markup-provider=maruku",
+    "--markup-provider=redcarpet",
     "--no-private",
     "--no-cache",
     "--protected",

data/her.gemspec

@@ -19,11 +19,11 @@ Gem::Specification.new do |s|
   s.add_development_dependency "rake"
   s.add_development_dependency "rspec"
   s.add_development_dependency "yard"
-  s.add_development_dependency "maruku"
+  s.add_development_dependency "redcarpet", "1.17.2"
   s.add_development_dependency "mocha"
   s.add_development_dependency "fakeweb"
 
   s.add_runtime_dependency "activesupport"
   s.add_runtime_dependency "faraday"
-  s.add_runtime_dependency "json"
+  s.add_runtime_dependency "multi_json"
 end

data/lib/her.rb

@@ -1,5 +1,5 @@
 require "her/version"
-require "json"
+require "multi_json"
 require "faraday"
 require "active_support"
 require "active_support/inflector"

data/lib/her/api.rb

@@ -1,49 +1,56 @@
 module Her
   # This class is where all HTTP requests are made. Before using Her, you must configure it
   # so it knows where to make those requests. In Rails, this is usually done in `config/initializers/her.rb`:
-  #
-  # @example
-  #   $my_api = Her::API.new
-  #   $my_api.setup :base_uri => "https://api.example.com"
   class API
     # @private
     attr_reader :base_uri, :middleware
 
-    # Setup a default API connection
+    # Setup a default API connection. Accepted arguments and options are the same as {API#setup}.
     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 # }}}
-
-    # @private
-    def self.default_middleware # {{{
-      [Faraday::Request::UrlEncoded, Faraday::Adapter::NetHttp]
-    end # }}}
-
-    # Setup the API connection
+    # Setup the API connection.
+    #
+    # @param [Hash] attrs the options to create a message with
+    # @option attrs [String] :base_uri The main HTTP API root (eg. `https://api.example.com`)
+    # @option attrs [Array, Class] :middleware A list of the only middleware Her will use
+    # @option attrs [Array, Class] :add_middleware A list of middleware to add to Her’s default middleware
+    # @option attrs [Class] :parse_middleware A middleware that will replace {Her::Middleware::DefaultParseJSON} to parse the received JSON
+    #
+    # @example Setting up the default API connection
+    #   Her::API.setup :base_uri => "https://api.example"
+    #
+    # @example A custom middleware added to the default list
+    #   class MyAuthentication < Faraday::Middleware
+    #     def call(env)
+    #       env[:request_headers]["X-API-Token"] = "bb2b2dd75413d32c1ac421d39e95b978d1819ff611f68fc2fdd5c8b9c7331192"
+    #       @all.call(env)
+    #     end
+    #   end
+    #   Her::API.setup :base_uri => "https://api.example.com", :add_middleware => [MyAuthentication]
     #
-    # @example
-    #   module MyAPI
-    #     class ParseResponse
-    #       def on_complete(env)
-    #         json = JSON.parse(env[:body], :symbolize_names => true)
-    #         {
-    #           :data => json,
-    #           :errors => json[:errors] || [],
-    #           :metadata => json[:metadata] || {},
-    #         }
-    #       end
+    # @example A custom parse middleware
+    #   class MyCustomParser < Faraday::Response::Middleware
+    #     def on_complete(env)
+    #       json = JSON.parse(env[:body], :symbolize_names => true)
+    #       errors = json.delete(:errors) || []
+    #       metadata = json.delete(:metadata) || []
+    #       env[:body] = { :data => json, :errors => errors, :metadata => metadata }
     #     end
     #   end
-    #   Her::API.setup :base_url => "https://api.example.com", :middleware => [MyAPI::ParseResponse, Faraday::Request::UrlEncoded, Faraday::Adapter::NetHttp]
+    #   Her::API.setup :base_uri => "https://api.example.com", :parse_middleware => MyCustomParser
     def setup(attrs={}) # {{{
       @base_uri = attrs[:base_uri]
-      middleware = @middleware = attrs[:middleware] || [Her::Middleware::DefaultParseJSON] + Her::API.default_middleware
+      @middleware = Her::API.default_middleware
+
+      @middleware = [attrs[:middleware]] if attrs[:middleware]
+      @middleware = [attrs[:add_middleware]] + @middleware if attrs[:add_middleware]
+      @middleware = [attrs[:parse_middleware]] + @middleware.reject { |item| item == Her::Middleware::DefaultParseJSON } if attrs[:parse_middleware]
+
+      @middleware.flatten!
+      middleware = @middleware
       @connection = Faraday.new(:url => @base_uri) do |builder|
         middleware.each { |m| builder.use(m) }
       end
@@ -53,9 +60,7 @@ module Her
     # expected to return a hash with three keys: a main data Hash, an errors Array
     # and a metadata Hash.
     #
-    # @example
-
-    # Make an HTTP request to the API
+    # @private
     def request(attrs={}) # {{{
       method = attrs.delete(:_method)
       path = attrs.delete(:_path)
@@ -71,5 +76,16 @@ module Her
       end
       response.env[:body]
     end # }}}
+
+    private
+    # @private
+    def self.default_api(attrs={}) # {{{
+      defined?(@@default_api) ? @@default_api : nil
+    end # }}}
+
+    # @private
+    def self.default_middleware # {{{
+      [Her::Middleware::DefaultParseJSON, Faraday::Request::UrlEncoded, Faraday::Adapter::NetHttp]
+    end # }}}
   end
 end

data/lib/her/middleware/default_parse_json.rb

@@ -1,18 +1,28 @@
 module Her
   module Middleware
+    # This is the default middleware used to parse JSON responses. It returns
+    # a Hash with three elements: `data`, `errors` and `metadata`.
     class DefaultParseJSON < Faraday::Response::Middleware
-      def parse(body)
-        json = JSON.parse(body, :symbolize_names => true)
-        return {
+      # Parse the response body
+      #
+      # @param [String] body The response body
+      # @return [Mixed] the parsed response
+      def parse(body) # {{{
+        json = MultiJson.load(body, :symbolize_keys => true)
+        {
           :data => json[:data],
           :errors => json[:errors],
-          :metadata => json[:metadata],
+          :metadata => json[:metadata]
         }
-      end
+      end # }}}
 
-      def on_complete(env)
-        env[:body] = parse env[:body]
-      end
+      # This method is triggered when the response has been received. It modifies
+      # the value of `env[:body]`.
+      #
+      # @param [Hash] env The response environment
+      def on_complete(env) # {{{
+        env[:body] = parse(env[:body])
+      end # }}}
     end
   end
 end

data/lib/her/model.rb

@@ -5,21 +5,23 @@ module Her
   # @example
   #   class User
   #     include Her::Model
-  #     uses_api $api
   #   end
   #
   #   @user = User.new(:name => "Rémi")
+  #   @user.save
   module Model
     autoload :Base,          "her/model/base"
     autoload :HTTP,          "her/model/http"
     autoload :ORM,           "her/model/orm"
     autoload :Relationships, "her/model/relationships"
     autoload :Hooks,         "her/model/hooks"
+    autoload :Introspection, "her/model/introspection"
 
     extend ActiveSupport::Concern
 
     # Instance methods
     include Her::Model::ORM
+    include Her::Model::Introspection
 
     # Class methods
     included do

data/lib/her/model/hooks.rb

@@ -1,7 +1,57 @@
 module Her
   module Model
+    # Her supports hooks/callbacks that are triggered whenever resources are created, updated or destroyed.
+    #
+    # @example Defining a hook with a block
+    #   class User
+    #     include Her::Model
+    #     before_save { |resource| resource.internal_id = 42 }
+    #   end
+    #
+    # @example Defining a hook with a method name
+    #   class User
+    #     include Her::Model
+    #     before_save :set_internal_id
+    #
+    #     private
+    #     def set_internal_id
+    #       self.internal_id = 42
+    #     end
+    #   end
     module Hooks
-      # Return hooks
+      # Add a *before save* callback. Triggered before a resource is created or updated.
+      # @param [Symbol, &block] method A method or a block to be called
+      def before_save(method=nil, &block); set_hook(:before, :save, method || block); end
+
+      # Add a *before create* callback. Triggered before a resource is created.
+      # @param [Symbol, &block] method A method or a block to be called
+      def before_create(method=nil, &block); set_hook(:before, :create, method || block); end
+
+      # Add a *before update* callback. Triggered before a resource is updated.
+      # @param [Symbol, &block] method A method or a block to be called
+      def before_update(method=nil, &block); set_hook(:before, :update, method || block); end
+
+      # Add a *before destroy* callback. Triggered before a resource is destroyed.
+      # @param [Symbol, &block] method A method or a block to be called
+      def before_destroy(method=nil, &block); set_hook(:before, :destroy, method || block); end
+
+      # Add a *after save* callback. Triggered after a resource is created or updated.
+      # @param [Symbol, &block] method A method or a block to be called
+      def after_save(method=nil, &block); set_hook(:after, :save, method || block); end
+
+      # Add a *after create* callback. Triggered after a resource is created.
+      # @param [Symbol, &block] method A method or a block to be called
+      def after_create(method=nil, &block); set_hook(:after, :create, method || block); end
+
+      # Add a *after update* callback. Triggered after a resource is updated.
+      # @param [Symbol, &block] method A method or a block to be called
+      def after_update(method=nil, &block); set_hook(:after, :update, method || block); end
+
+      # Add a *after destroy* callback. Triggered after a resource is destroyed.
+      # @param [Symbol, &block] method A method or a block to be called
+      def after_destroy(method=nil, &block); set_hook(:after, :destroy, method || block); end
+
+      private
       # @private
       def hooks # {{{
         @her_hooks
@@ -25,16 +75,6 @@ module Her
           end
         end
       end # }}}
-
-      def before_save(method=nil, &block); set_hook(:before, :save, method || block); end
-      def before_create(method=nil, &block); set_hook(:before, :create, method || block); end
-      def before_update(method=nil, &block); set_hook(:before, :update, method || block); end
-      def before_destroy(method=nil, &block); set_hook(:before, :destroy, method || block); end
-
-      def after_save(method=nil, &block); set_hook(:after, :save, method || block); end
-      def after_create(method=nil, &block); set_hook(:after, :create, method || block); end
-      def after_update(method=nil, &block); set_hook(:after, :update, method || block); end
-      def after_destroy(method=nil, &block); set_hook(:after, :destroy, method || block); end
-    end # }}}
+    end
   end
 end