Faraday HTTP Client Documentation

Faraday is an HTTP client library abstraction layer for Ruby. It provides a common interface over various adapters (such as Net::HTTP, Typhoeus, Patron, Excon, and HTTPClient) and uses a middleware pattern inspired by Rack to process the request/response cycle.

Key features include:

• Support for multiple adapters
• Persistent connections (keep-alive)
• Parallel requests
• Automatic response parsing (JSON, XML, YAML)
• Customization via middleware
• Streaming responses and file uploads

Faraday is transitioning its options subclasses (like ConnectionOptions, RequestOptions, SSLOptions, etc.) from inheriting from Faraday::Options to a new explicit OOP structure based on Faraday::BaseOptions.

Key concepts:

• Faraday::OptionsLike: A marker module used to identify objects that behave like options objects. This allows utilities like Utils.deep_merge! to treat them with the same logic as legacy Options objects.
• Faraday::BaseOptions: An abstract superclass that provides centralized logic for .from, .update, .merge!, .merge, .deep_dup, .to_hash, and .inspect. It also handles nested coercion via a COERCIONS constant.

Note: For detached subclasses, legacy ergonomics such as Struct indexing, .fetch, .each_key, and the .options/.memoized macros are being dropped in favor of explicit accessors.

Faraday uses an env object to pass data between middleware. This object is initialized at the start of a request and passed down the middleware stack. The adapter executes the HTTP request and populates the response property on the env object, which is then passed back up the middleware stack.

Key lifecycle behavior:

• Request phase: Configuration and request properties are available.
• Response phase: Response properties (like :status and :response_body) are only available after the request has been performed, typically within the on_complete callback of a middleware.

Faraday provides several built-in capabilities for managing HTTP communication:

• Multiple Adapters: Use different underlying libraries like Net::HTTP, Typhoeus, Patron, Excon, or HTTPClient through a unified interface.
• Middleware Support: Customize the request/response cycle using Rack-style middleware.
• Connection Management: Supports persistent connections (keep-alive).
• Concurrency: Supports parallel requests.
• Automatic Parsing: Handles automatic response parsing for JSON, XML, and YAML.
• Advanced HTTP Operations: Supports streaming responses and file uploads.

By default, the an adapter test suite only checks for required behavior. If your adapter supports optional Faraday features (like streaming or compression), you can enable specific test expectations by calling the features method before the it_behaves_like 'an adapter' call.

RSpec.describe Faraday::Adapter::MyAdapter do
  # Use the `features` method to turn on only the ones you know you can support.
  features :request_body_on_query_methods,
           :compression,
           :streaming

  # Runs the tests provided by Faraday, according to the features specified above.
  it_behaves_like 'an adapter'
end

The built-in Faraday Test adapter allows you to define stubbed HTTP requests to mock network services in unit tests. When stubbing a request, the block must return an Array containing three items:

1. An Integer representing the HTTP status code.
2. A Hash of HTTP headers.
3. A String representing the response body.

You can also stub exceptions by raising them within the stub block.

conn = Faraday.new do |builder|
  builder.adapter :test do |stub|
    # Stubbing a GET request
    stub.get('/ebi') do |env|
      [
        200,
        { 'Content-Type': 'text/plain' },
        'shrimp'
      ]
    end

    # Stubbing an exception
    stub.get('/boom') do
      raise Faraday::ConnectionFailed
    end
  end
end

Faraday supports and is tested against officially supported Ruby implementations.

Current Support: Ruby 3.0+

In Faraday 1.x, the middleware usage differs from 2.x. Instead of a single :authorization request type, you use specific methods for different authentication types:

• Basic Auth: Use conn.request :basic_auth, 'username', 'password'
• Token Auth: Use conn.request :token_auth, 'authentication-token', **options. The options are automatically converted into key=value format in the header.
• Generic Auth (Bearer): Use conn.request :authorization, 'Bearer', 'authentication-token'

# Faraday 1.x Basic Auth
Faraday.new(...) do |conn|
  conn.request :basic_auth, 'username', 'password'
end

# Faraday 1.x Token Auth
Faraday.new(...) do |conn|
  conn.request :token_auth, 'authentication-token', **options
end

# Faraday 1.x Generic Auth
Faraday.new(...) do |conn|
  conn.request :authorization, 'Bearer', 'authentication-token'
end

To preview your documentation changes locally, use the docs script via npm. This uses Docsify to power the documentation site.

npm run docs