Under the hood, Faraday uses a Rack-inspired middleware stack for making requests. Much of Faraday’s power is unlocked with custom middleware. Some middleware is included with Faraday, and others are in external gems.
Here are some of the features that middleware can provide:
- caching responses on disk or in memory
- following redirects
- JSON encoding/decoding
To use these great features, create a
and add the correct middleware in a block. For example:
require 'faraday' conn = Faraday.new do |f| f.request :json # encode req bodies as JSON f.request :logger # logs request and responses f.response :json # decode response bodies as JSON f.adapter :net_http # Use the Net::HTTP adapter end response = conn.get("http://httpbingo.org/get")
How it Works
Faraday::Connection uses a
Faraday::RackBuilder to assemble a
Rack-inspired middleware stack for making HTTP requests. Each middleware runs
and passes an Env object around to the next one. After the final middleware has
run, Faraday will return a
Faraday::Response to the end user.
The order in which middleware is stacked is important. Like with Rack, the first middleware on the list wraps all others, while the last middleware is the innermost one. If you want to use a custom adapter, it must therefore be last.
use is the most basic way to add middleware to your stack, but most
middleware is conveniently registered in the
namespaces. All four methods are equivalent apart from the namespacing.
For example, the
Faraday::Request::UrlEncoded middleware registers itself in
Faraday::Request so it can be added with
request. These two are equivalent:
# add by symbol, lookup from Faraday::Request, # Faraday::Response and Faraday::Adapter registries conn = Faraday.new do |f| f.request :url_encoded f.response :logger f.adapter :net_http end
# identical, but add the class directly instead of using lookups conn = Faraday.new do |f| f.use Faraday::Request::UrlEncoded f.use Faraday::Response::Logger f.use Faraday::Adapter::NetHttp end
This is also the place to pass options. For example:
conn = Faraday.new do |f| f.request :logger, bodies: true end
We also have great documentation for the middleware that ships with Faraday.
Here’s a more realistic example:
Faraday.new(...) do |conn| # POST/PUT params encoder conn.request :url_encoded # Logging of requests/responses conn.response :logger # Last middleware must be the adapter conn.adapter :net_http end
This request middleware setup affects POST/PUT requests in the following way:
Request::UrlEncodedencodes as “application/x-www-form-urlencoded” if not already encoded or of another type.
Response::Loggerlogs request and response headers, can be configured to log bodies as well.
Swapping middleware means giving the other priority. Specifying the “Content-Type” for the request is explicitly stating which middleware should process it.