index.md

layout	title	permalink	next_name	next_link	order
documentation	Middleware	/middleware/	Available Middleware	./list	3

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:

• authentication
• caching responses on disk or in memory
• cookies
• following redirects
• JSON encoding/decoding
• logging
• retrying

To use these great features, create a Faraday::Connection with Faraday.new and add the correct middleware in a block. For example:

require 'faraday_middleware'

conn = Faraday.new do |f|
  f.request :json # encode req bodies as JSON
  f.request :retry # retry transient failures
  f.response :follow_redirects # follow redirects
  f.response :json # decode response bodies as JSON
end
response = conn.get("http://httpbingo.org/get")

How it Works

A 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.

Using Middleware

Calling use is the most basic way to add middleware to your stack, but most middleware is conveniently registered in the request, response or adapter 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:

require 'faraday_middleware'

conn = Faraday.new do |f|
  # add by symbol, lookup from Faraday::Request registry
  f.request :url_encoded
  # add by symbol, lookup from Faraday::Response registry
  f.response :follow_redirects
  # add by symbol, lookup from Faraday::Adapter registry
  f.adapter :httpclient

  # or

  # identical, but add the class directly
  f.use Faraday::Request::UrlEncoded
  f.use FaradayMiddleware::FollowRedirects
  f.use Faraday::Adapter::HTTPClient
end

This is also the place to pass options. For example:

conn = Faraday.new do |f|
  f.request :retry, max: 10
end

Available Middleware

The Awesome Faraday project has a complete list of useful, well-maintained Faraday middleware. Middleware is often provided by external gems, like the faraday-middleware gem.

We also have great documentation for the middleware that ships with Faraday.

Detailed Example

Here's a more realistic example:

Faraday.new(...) do |conn|
  # POST/PUT params encoders:
  conn.request :multipart
  conn.request :url_encoded

  # Last middleware must be the adapter:
  conn.adapter :typhoeus
end

This request middleware setup affects POST/PUT requests in the following way:

1. Request::Multipart checks for files in the payload, otherwise leaves everything untouched;
2. Request::UrlEncoded encodes as "application/x-www-form-urlencoded" if not already encoded or of another type

Swapping middleware means giving the other priority. Specifying the "Content-Type" for the request is explicitly stating which middleware should process it.

For example:

# uploading a file:
payload[:profile_pic] = Faraday::FilePart.new('/path/to/avatar.jpg', 'image/jpeg')

# "Multipart" middleware detects files and encodes with "multipart/form-data":
conn.put '/profile', payload