Permalink
Browse files

README + tweaks

  • Loading branch information...
mislav committed Mar 28, 2011
1 parent 4c804bf commit 81c53813126fb3d1ebcb901dda728b4834d66bbd
Showing with 71 additions and 4 deletions.
  1. +61 −0 README.md
  2. +1 −1 lib/faraday_stack.rb
  3. +9 −3 lib/faraday_stack/instrumentation.rb
View
@@ -0,0 +1,61 @@
+# Über Stack
+
+[Faraday][] is an HTTP client lib that provides a common interface over many adapters (such as Net::HTTP) and embraces the concept of Rack middleware when processing the request/response cycle.
+
+*“Faraday Stack”* is an add-on library that implements several middleware (such as JSON and XML parsers) and helps you build an awesome stack that covers most of your API-consuming needs.
+
+Boring example:
+
+ require 'faraday_stack'
+
+ response = FaradayStack.get 'http://google.com'
+
+ response.headers['content-type'] #=> "text/html; charset=UTF-8"
+ response.headers['location'] #=> "http://www.google.com/"
+ puts response.body
+
+Awesome example:
+
+ conn = FaradayStack.build 'http://github.com/api/v2'
+
+ # JSON resource
+ resp = conn.get 'json/repos/show/mislav/faraday-stack'
+ resp.body
+ #=> {"repository"=>{"language"=>"Ruby", "fork"=>false, ...}}
+
+ # XML resource
+ resp = conn.get 'xml/repos/show/mislav/faraday-stack'
+ resp.body.class
+ #=> Nokogiri::XML::Document
+
+ # 404
+ conn.get 'zomg/wrong/url'
+ #=> raises Faraday::Error::ResourceNotFound
+
+## Features
+
+* parses JSON, XML & HTML
+* raises exceptions on 4xx, 5xx responses
+* follows redirects
+
+Optional features:
+
+* encode POST/PUT bodies as JSON:
+
+ conn.post(path, payload, :content_type => 'application/json')
+
+* add `Instrumentation` middleware to instrument requests with ActiveSupport
+
+ conn.builder.insert_after Faraday::Response::RaiseError, FaradayStack::Instrumentation
+
+* add `Caching` middleware to have GET responses cached
+
+ conn.builder.insert_before FaradayStack::ResponseJSON, FaradayStack::Caching do
+ ActiveSupport::Cache::FileStore.new 'tmp/cache',
+ :namespace => 'faraday', :expires_in => 3600
+ end
+
+To see how the default stack is built, see "[faraday_stack.rb][source]".
+
+[faraday]: https://github.com/technoweenie/faraday
+[source]: https://github.com/mislav/faraday-stack/blob/master/lib/faraday_stack.rb
View
@@ -30,9 +30,9 @@ def self.build(url = nil, options = {})
builder.request :url_encoded
builder.request :json
yield builder if block_given?
- builder.use ResponseJSON, :content_type => 'application/json'
builder.use ResponseXML, :content_type => /[+\/]xml$/
builder.use ResponseHTML, :content_type => 'text/html'
+ builder.use ResponseJSON, :content_type => 'application/json'
builder.use FollowRedirects
builder.response :raise_error
builder.adapter Faraday.default_adapter
@@ -1,5 +1,3 @@
-require 'active_support/notifications'
-
module FaradayStack
# Measures request time only in synchronous request mode.
# Sample subscriber:
@@ -11,8 +9,16 @@ module FaradayStack
# $stderr.puts '[%s] %s %s (%.3f s)' % [url.host, http_method, url.request_uri, duration]
# end
class Instrumentation < Faraday::Middleware
+ dependency 'active_support/notifications'
+
+ def initialize(app, options = {})
+ super(app)
+ @options = options
+ @name = options[:name] || 'request.faraday'
+ end
+
def call(env)
- ActiveSupport::Notifications.instrument('request.faraday', env) do
+ ActiveSupport::Notifications.instrument(@name, env) do
@app.call(env)
end
end

0 comments on commit 81c5381

Please sign in to comment.