her 0.2.5 → 0.2.6

data/.rspec

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

data/README.md

@@ -1,9 +1,7 @@
-# Her
+# Her [![Build Status](https://secure.travis-ci.org/remiprev/her.png)](http://travis-ci.org/remiprev/her) [![Gem dependency status](https://gemnasium.com/remiprev/her.png?travis)](https://gemnasium.com/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 instead of a database.
 
-[![Build Status](https://secure.travis-ci.org/remiprev/her.png)](http://travis-ci.org/remiprev/her)
-
 ## Installation
 
 In your Gemfile, add:
@@ -24,10 +22,10 @@ First, you have to define which API your models will be bound to. For example, w
 
 ```ruby
 # config/initializers/her.rb
-Her::API.setup :base_uri => "https://api.example.com" do |builder|
-  builder.use Faraday::Request::UrlEncoded
-  builder.use Her::Middleware::DefaultParseJSON
-  builder.use Faraday::Adapter::NetHttp
+Her::API.setup :url => "https://api.example.com" do |connection|
+  connection.use Faraday::Request::UrlEncoded
+  connection.use Her::Middleware::DefaultParseJSON
+  connection.use Faraday::Adapter::NetHttp
 end
 ```
 
@@ -62,13 +60,15 @@ User.find(1)
 # PUT https://api.example.com/users/1 with the data and return+update the User object
 ```
 
+You can look into the `examples` directory for sample applications using Her.
+
 ## 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. Using the 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.
+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 the block in the `setup` call, you have access to Faraday’s `connection` object and are able to customize the middleware stack used on each request and response.
 
 ### Authentication
 
-Her doesn’t support any kind of authentication. However, it’s very easy to implement one with a request middleware. Using the builder block, we add it to the default list of middleware.
+Her doesn’t support any kind of authentication. However, it’s very easy to implement one with a request middleware. Using the connection block, we add it to the default list of middleware.
 
 ```ruby
 class MyAuthentication < Faraday::Middleware
@@ -82,13 +82,13 @@ class MyAuthentication < Faraday::Middleware
   end
 end
 
-Her::API.setup :base_uri => "https://api.example.com" do |builder|
+Her::API.setup :url => "https://api.example.com" do |connection|
   # This token could be stored in the client session
-  builder.use MyAuthentication, :token => "bb2b2dd75413d32c1ac421d39e95b978d1819ff611f68fc2fdd5c8b9c7331192"
+  connection.use MyAuthentication, :token => "bb2b2dd75413d32c1ac421d39e95b978d1819ff611f68fc2fdd5c8b9c7331192"
 
-  builder.use Faraday::Request::UrlEncoded
-  builder.use Her::Middleware::DefaultParseJSON
-  builder.use Faraday::Adapter::NetHttp
+  connection.use Faraday::Request::UrlEncoded
+  connection.use Her::Middleware::DefaultParseJSON
+  connection.use Faraday::Adapter::NetHttp
 end
 ```
 
@@ -106,7 +106,7 @@ 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 with our custom 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 connection block, we then replace the default parser with our custom parser.
 
 ```ruby
 class MyCustomParser < Faraday::Response::Middleware
@@ -120,10 +120,10 @@ class MyCustomParser < Faraday::Response::Middleware
   end
 end
 
-Her::API.setup :base_uri => "https://api.example.com" do |builder|
-  builder.use Faraday::Request::UrlEncoded
-  builder.use MyCustomParser
-  builder.use Faraday::Adapter::NetHttp
+Her::API.setup :url => "https://api.example.com" do |connection|
+  connection.use Faraday::Request::UrlEncoded
+  connection.use MyCustomParser
+  connection.use Faraday::Adapter::NetHttp
 end
 # User.find(1) will now expect "https://api.example.com/users/1" to return something like '{ "result" => { "id": 1, "name": "Tobias Fünke" }, "errors" => [] }'
 ```
@@ -151,11 +151,11 @@ TWITTER_CREDENTIALS = {
   :token_secret => ""
 }
 
-Her::API.setup :base_uri => "https://api.twitter.com/1/" do |builder|
-  builder.use FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
-  builder.use Faraday::Request::UrlEncoded
-  builder.use Her::Middleware::DefaultParseJSON
-  builder.use Faraday::Adapter::NetHttp
+Her::API.setup :url => "https://api.twitter.com/1/" do |connection|
+  connection.use FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
+  connection.use Faraday::Request::UrlEncoded
+  connection.use Her::Middleware::DefaultParseJSON
+  connection.use Faraday::Adapter::NetHttp
 end
 
 class Tweet
@@ -199,11 +199,11 @@ end
 # 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|
-  builder.use Faraday::Request::UrlEncoded
-  builder.use FaradayMiddleware::Caching, $cache
-  builder.use Her::Middleware::DefaultParseJSON
-  builder.use Faraday::Adapter::NetHttp
+Her::API.setup :url => "https://api.example.com" do |connection|
+  connection.use Faraday::Request::UrlEncoded
+  connection.use FaradayMiddleware::Caching, $cache
+  connection.use Her::Middleware::DefaultParseJSON
+  connection.use Faraday::Adapter::NetHttp
 end
 
 class User
@@ -403,17 +403,17 @@ It is possible to use different APIs for different models. Instead of calling `H
 ```ruby
 # config/initializers/her.rb
 $my_api = Her::API.new
-$my_api.setup :base_uri => "https://my_api.example.com" do |builder|
-  builder.use Faraday::Request::UrlEncoded
-  builder.use Her::Middleware::DefaultParseJSON
-  builder.use Faraday::Adapter::NetHttp
+$my_api.setup :url => "https://my_api.example.com" do |connection|
+  connection.use Faraday::Request::UrlEncoded
+  connection.use Her::Middleware::DefaultParseJSON
+  connection.use Faraday::Adapter::NetHttp
 end
 
 $other_api = Her::API.new
-$other_api.setup :base_uri => "https://other_api.example.com" do |builder|
-  builder.use Faraday::Request::UrlEncoded
-  builder.use Her::Middleware::DefaultParseJSON
-  builder.use Faraday::Adapter::NetHttp
+$other_api.setup :url => "https://other_api.example.com" do |connection|
+  connection.use Faraday::Request::UrlEncoded
+  connection.use Her::Middleware::DefaultParseJSON
+  connection.use Faraday::Adapter::NetHttp
 end
 ```
 
@@ -437,6 +437,51 @@ Category.all
 # GET https://other_api.example.com/categories
 ```
 
+## SSL
+
+When initializing `Her::API`, you can pass any parameter supported by `Faraday.new`. So [to use HTTPS](https://github.com/technoweenie/faraday/wiki/Setting-up-SSL-certificates), you can use Faraday’s `:ssl` option.
+
+```ruby
+ssl_options = { :ca_path => "/usr/lib/ssl/certs" }
+Her::API.setup :url => "https://api.example.com", :ssl => ssl_options do |connection|
+  connection.use Faraday::Request::UrlEncoded
+  connection.use Her::Middleware::DefaultParseJSON
+  connection.use Faraday::Adapter::NetHttp
+end
+```
+
+## Testing
+
+Using Faraday stubbing feature, it’s very easy to write tests for our models. For example, using [RSpec](https://github.com/rspec/rspec-core):
+
+```ruby
+# app/models/post.rb
+class Post
+  include Her::Model
+  custom_get :popular
+end
+
+# spec/models/post.rb
+describe Post do
+  before do
+    Her::API.setup :url => "http://api.example.com" do |connection|
+      connection.use Her::Middleware::FirstLevelParseJSON
+      connection.use Faraday::Request::UrlEncoded
+      connection.adapter :test do |stub|
+        stub.get("/users/popular") { |env| [200, {}, [{ :id => 1, :name => "Tobias Fünke" }, { :id => 2, :name => "Lindsay Fünke" }].to_json] }
+      end
+    end
+  end
+
+  describe ".popular" do
+    it "should fetch all popular posts" do
+      @posts = Post.popular
+      @posts.length.should == 2
+    end
+  end
+end
+```
+
 ## Things to be done
 
 * Better error handling
@@ -464,6 +509,7 @@ These fine folks helped with Her:
 * [@rafaelss](https://github.com/rafaelss)
 * [@tysontate](https://github.com/tysontate)
 * [@nfo](https://github.com/nfo)
+* [@simonprevost](https://github.com/simonprevost)
 
 ## License
 

data/Rakefile

@@ -9,7 +9,6 @@ task :default => :spec
 desc "Run all specs"
 RSpec::Core::RakeTask.new(:spec) do |task| # {{{
   task.pattern = "spec/**/*_spec.rb"
-  task.rspec_opts = "--colour --format=documentation"
 end # }}}
 
 desc "Generate YARD Documentation"

data/UPGRADE.md

@@ -1,20 +1,20 @@
-Here is a list of backward-incompatible changes that were introduced while Her is still \<1.0. After reaching 1.0, it will follow the [Semantic Versioning](http://semver.org/) system.
+Here is a list of backward-incompatible changes that were introduced while Her is pre-1.0. After reaching 1.0, it will follow the [Semantic Versioning](http://semver.org/) system.
 
 ## 0.2.4
 
 * Her no longer includes default middleware when making HTTP requests. The user has now to define all the needed middleware. Before:
 
-        Her::API.setup :base_uri => "https://api.example.com" do |builder|
-          builder.insert(0, FaradayMiddle::OAuth)
+        Her::API.setup :url => "https://api.example.com" do |connection|
+          connection.insert(0, FaradayMiddle::OAuth)
         end
 
   Now:
-    
-        Her::API.setup :base_uri => "https://api.example.com" do |builder|
-          builder.use FaradayMiddle::OAuth
-          builder.use Her::Middleware::FirstLevelParseJSON
-          builder.use Faraday::Request::UrlEncoded
-          builder.use Faraday::Adapter::NetHttp
+
+        Her::API.setup :url => "https://api.example.com" do |connection|
+          connection.use FaradayMiddle::OAuth
+          connection.use Her::Middleware::FirstLevelParseJSON
+          connection.use Faraday::Request::UrlEncoded
+          connection.use Faraday::Adapter::NetHttp
         end
 
 ## 0.2
@@ -22,9 +22,9 @@ Here is a list of backward-incompatible changes that were introduced while Her i
 * The default parser middleware has been replaced to treat first-level JSON data as the resource or collection data. Before it expected this:
 
         { "data": { "id": 1, "name": "Foo" }, "errors": [] }
-        
+
    Now it expects this (the `errors` key is not treated as resource data):
-   
+
         { "id": 1, "name": "Foo", "errors": [] }
-      
-   If you still want to get the old behavior, you can use `Her::Middleware::SecondLevelParseJSON` instead of `Her::Middleware::FirstLevelParseJSON` in your middleware stack.
+
+   If you still want to get the old behavior, you can use `Her::Middleware::SecondLevelParseJSON` instead of `Her::Middleware::FirstLevelParseJSON` in your middleware stack.

data/examples/twitter-oauth/app.rb

@@ -1,7 +1,5 @@
 # Create custom parser
 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)
     json = MultiJson.load(env[:body], :symbolize_keys => true)
     errors = [json.delete(:error)]
@@ -13,6 +11,7 @@ class TwitterParser < Faraday::Response::Middleware
   end
 end
 
+# See https://dev.twitter.com/apps
 TWITTER_CREDENTIALS = {
   :consumer_key => "",
   :consumer_secret => "",
@@ -21,9 +20,11 @@ TWITTER_CREDENTIALS = {
 }
 
 # Initialize API
-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
+Her::API.setup :url => "https://api.twitter.com/1/" do |builder|
+  builder.use FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
+  builder.use Faraday::Request::UrlEncoded
+  builder.use TwitterParser
+  builder.use Faraday::Adapter::NetHttp
 end
 
 # Define classes

data/examples/twitter-search/app.rb

@@ -4,10 +4,12 @@ class TwitterSearchParser < Faraday::Response::Middleware
 
   def on_complete(env)
     json = MultiJson.load(env[:body], :symbolize_keys => true)
+    data = json.delete(:results)
+    errors = [json.delete(:error)].compact
     env[:body] = {
-      :data => json[:results],
-      :errors => [json[:error]],
-      :metadata => json.select { |key, value| METADATA_KEYS.include?(key) }
+      :data => data,
+      :errors => errors,
+      :metadata => json
     }
   end
 end
@@ -31,11 +33,11 @@ end
 $cache = MyCache.new
 
 # Initialize API
-Her::API.setup :base_uri => "http://search.twitter.com" do |builder|
-  builder.use Faraday::Request::UrlEncoded
-  builder.use FaradayMiddleware::Caching, $cache
-  builder.use TwitterSearchParser
-  builder.use Faraday::Adapter::NetHttp
+Her::API.setup :url => "http://search.twitter.com" do |connection|
+  connection.use Faraday::Request::UrlEncoded
+  connection.use FaradayMiddleware::Caching, $cache
+  connection.use TwitterSearchParser
+  connection.use Faraday::Adapter::NetHttp
 end
 
 # Define classes

data/her.gemspec

@@ -8,6 +8,7 @@ Gem::Specification.new do |s|
   s.authors     = ["Rémi Prévost"]
   s.email       = ["remi@exomel.com"]
   s.homepage    = "http://remiprev.github.com/her"
+  s.license     = "MIT"
   s.summary     = "A simple Representational State Transfer-based Hypertext Transfer Protocol-powered Object Relational Mapper. Her?"
   s.description = "Her is an ORM that maps REST resources and collections to Ruby objects"
 
@@ -16,18 +17,17 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_development_dependency "rake", "0.9.2.2"
-  s.add_development_dependency "rspec", "2.9.0"
-  s.add_development_dependency "yard", "0.7.5"
-  s.add_development_dependency "redcarpet", "1.17.2"
-  s.add_development_dependency "mocha", "0.11.3"
-  s.add_development_dependency "fakeweb", "1.3.0"
-  s.add_development_dependency "guard", "1.0.1"
-  s.add_development_dependency "guard-rspec", "0.7.0"
-  s.add_development_dependency "rb-fsevent", "0.9.1"
-  s.add_development_dependency "growl", "1.0.3"
+  s.add_development_dependency "rake", "~> 0.9.2"
+  s.add_development_dependency "rspec", "~> 2.10"
+  s.add_development_dependency "yard", "~> 0.8"
+  s.add_development_dependency "redcarpet", "~> 2.1"
+  s.add_development_dependency "mocha", "~> 0.11"
+  s.add_development_dependency "guard", "~> 1.0"
+  s.add_development_dependency "guard-rspec", "~> 0.7"
+  s.add_development_dependency "rb-fsevent", "~> 0.9"
+  s.add_development_dependency "growl", "~> 1.0"
 
-  s.add_runtime_dependency "activesupport", "3.2.3"
-  s.add_runtime_dependency "faraday", "0.8.0"
-  s.add_runtime_dependency "multi_json", "1.3.4"
+  s.add_runtime_dependency "activesupport", "~> 3.2"
+  s.add_runtime_dependency "faraday", "~> 0.8"
+  s.add_runtime_dependency "multi_json", "~> 1.3"
 end

data/lib/her.rb

@@ -1,12 +1,15 @@
 require "her/version"
+
 require "multi_json"
 require "faraday"
 require "active_support"
 require "active_support/inflector"
 
+require "her/model"
+require "her/api"
+require "her/middleware"
+require "her/errors"
+require "her/collection"
+
 module Her
-  autoload :Model,       "her/model"
-  autoload :API,         "her/api"
-  autoload :Middleware,  "her/middleware"
-  autoload :Errors,      "her/errors"
 end

data/lib/her/api.rb

@@ -3,7 +3,7 @@ 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, :connection
+    attr_reader :base_uri, :connection, :options
 
     # Setup a default API connection. Accepted arguments and options are the same as {API#setup}.
     def self.setup(attrs={}, &block) # {{{
@@ -13,13 +13,14 @@ module Her
 
     # 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`)
+    # @param [Hash] attrs the Faraday options
+    # @option attrs [String] :url The main HTTP API root (eg. `https://api.example.com`)
+    # @option attrs [String] :ssl A hash containing [SSL options](https://github.com/technoweenie/faraday/wiki/Setting-up-SSL-certificates)
     #
     # @return Faraday::Connection
     #
     # @example Setting up the default API connection
-    #   Her::API.setup :base_uri => "https://api.example"
+    #   Her::API.setup :url => "https://api.example"
     #
     # @example A custom middleware added to the default list
     #   class MyAuthentication < Faraday::Middleware
@@ -28,8 +29,10 @@ module Her
     #       @all.call(env)
     #     end
     #   end
-    #   Her::API.setup :base_uri => "https://api.example.com" do |builder|
-    #     builder.use MyAuthentication
+    #   Her::API.setup :url => "https://api.example.com" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use Her::Middleware::DefaultParseJSON
+    #     connection.use Faraday::Adapter::NetHttp
     #   end
     #
     # @example A custom parse middleware
@@ -41,14 +44,17 @@ module Her
     #       env[:body] = { :data => json, :errors => errors, :metadata => metadata }
     #     end
     #   end
-    #   Her::API.setup :base_uri => "https://api.example.com" do |builder|
-    #     builder.delete Her::Middleware::DefaultParseJSON
-    #     builder.use MyCustomParser
+    #   Her::API.setup :url => "https://api.example.com" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use MyCustomParser
+    #     connection.use Faraday::Adapter::NetHttp
     #   end
     def setup(attrs={}) # {{{
-      @base_uri = attrs[:base_uri]
-      @connection = Faraday.new(:url => @base_uri) do |connection|
-        yield connection.builder if block_given?
+      attrs[:url] = attrs.delete(:base_uri) if attrs.include?(:base_uri) # Support legacy :base_uri option
+      @base_uri = attrs[:url]
+      @options = attrs
+      @connection = Faraday.new(attrs) do |connection|
+        yield connection if block_given?
       end
     end # }}}
 
@@ -60,8 +66,10 @@ module Her
     def request(attrs={}) # {{{
       method = attrs.delete(:_method)
       path = attrs.delete(:_path)
+      headers = attrs.delete(:_headers)
       attrs.delete_if { |key, value| key.to_s =~ /^_/ } # Remove all internal parameters
       response = @connection.send method do |request|
+        request.headers.merge!(headers) if headers
         if method == :get
           # For GET requests, treat additional parameters as querystring data
           request.url path, attrs