lib/her/api.rb in her-0.1.7 vs lib/her/api.rb in her-0.1.8

@@ -1,63 +1,68 @@
 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.
     #
-    # @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
+    # @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_url => "https://api.example.com", :middleware => [MyAPI::ParseResponse, Faraday::Request::UrlEncoded, Faraday::Adapter::NetHttp]
+    #   Her::API.setup :base_uri => "https://api.example.com", :add_middleware => [MyAuthentication]
+    #
+    # @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_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
     end # }}}
 
     # Define a custom parsing procedure. The procedure is passed the response object and is
     # 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)
       response = @connection.send method do |request|
         if method == :get
@@ -68,8 +73,19 @@
           request.url path
           request.body = attrs
         end
       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