[deprecated] Über Faraday stack for consuming APIs (JSON, XML decoding & more)
Latest commit fabe67e Jan 29, 2012 @mislav v0.1.5
Failed to load latest commit information.
test fix parsing back headers in RackCompatible middleware Jan 10, 2012
Gemfile add rake test Jan 10, 2012
README.md deprecated in favor of faraday_middleware Jan 24, 2012


Über Stack

Notice: faraday-stack has been deprecated and its middleware moved to faraday_middleware.

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'
#=> {"repository"=>{"language"=>"Ruby", "fork"=>false, ...}}

# XML resource
resp = conn.get 'xml/repos/show/mislav/faraday-stack'
#=> Nokogiri::XML::Document

# 404
conn.get 'zomg/wrong/url'
#=> raises Faraday::Error::ResourceNotFound


  • parses JSON, XML & HTML
  • raises exceptions on 4xx, 5xx responses
  • follows redirects

To see how the default stack is built, see "faraday_stack.rb".

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
  • mount Rack::Cache through RackCompatible middleware for HTTP caching of responses

    conn.builder.insert_after FaradayStack::FollowRedirects, FaradayStack::RackCompatible,
        :metastore   => "file:/var/cache/rack/meta",
        :entitystore => "file:/var/cache/rack/body"