Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 75 lines (47 sloc) 2.592 kb
81c5381 @mislav README + tweaks
authored
1 # Über Stack
2
c73aa6e @mislav deprecated in favor of faraday_middleware
authored
3 **Notice: faraday-stack has been deprecated and its middleware moved to [faraday_middleware](https://github.com/pengwynn/faraday_middleware#readme).**
4
5 ---
6
81c5381 @mislav README + tweaks
authored
7 [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.
8
9 *“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.
10
11 Boring example:
12
13 require 'faraday_stack'
14
15 response = FaradayStack.get 'http://google.com'
16
17 response.headers['content-type'] #=> "text/html; charset=UTF-8"
18 response.headers['location'] #=> "http://www.google.com/"
19 puts response.body
20
21 Awesome example:
22
23 conn = FaradayStack.build 'http://github.com/api/v2'
24
25 # JSON resource
26 resp = conn.get 'json/repos/show/mislav/faraday-stack'
27 resp.body
28 #=> {"repository"=>{"language"=>"Ruby", "fork"=>false, ...}}
29
30 # XML resource
31 resp = conn.get 'xml/repos/show/mislav/faraday-stack'
32 resp.body.class
33 #=> Nokogiri::XML::Document
34
35 # 404
36 conn.get 'zomg/wrong/url'
37 #=> raises Faraday::Error::ResourceNotFound
38
39 ## Features
40
41 * parses JSON, XML & HTML
42 * raises exceptions on 4xx, 5xx responses
43 * follows redirects
44
8a1eb00 @mislav document Rack::Cache through RackCompatible
authored
45 To see how the default stack is built, see "[faraday_stack.rb][source]".
46
47 ### Optional features:
81c5381 @mislav README + tweaks
authored
48
49 * encode POST/PUT bodies as JSON:
50
51 conn.post(path, payload, :content_type => 'application/json')
52
53 * add `Instrumentation` middleware to instrument requests with ActiveSupport
54
55 conn.builder.insert_after Faraday::Response::RaiseError, FaradayStack::Instrumentation
56
57 * add `Caching` middleware to have GET responses cached
58
59 conn.builder.insert_before FaradayStack::ResponseJSON, FaradayStack::Caching do
60 ActiveSupport::Cache::FileStore.new 'tmp/cache',
61 :namespace => 'faraday', :expires_in => 3600
62 end
63
8a1eb00 @mislav document Rack::Cache through RackCompatible
authored
64 * mount [Rack::Cache][] through `RackCompatible` middleware for HTTP caching of responses
65
66 conn.builder.insert_after FaradayStack::FollowRedirects, FaradayStack::RackCompatible,
67 Rack::Cache::Context,
68 :metastore => "file:/var/cache/rack/meta",
69 :entitystore => "file:/var/cache/rack/body"
70
81c5381 @mislav README + tweaks
authored
71
72 [faraday]: https://github.com/technoweenie/faraday
73 [source]: https://github.com/mislav/faraday-stack/blob/master/lib/faraday_stack.rb
8a1eb00 @mislav document Rack::Cache through RackCompatible
authored
74 [rack::cache]: http://rtomayko.github.com/rack-cache/
Something went wrong with that request. Please try again.