API documentation

Usage

Basic Use

A simple get request can be performed by using the syntax described above. This works if you don't need to set up anything; you can roll with just the default middleware
stack and default adapter (see Faraday::RackBuilder#initialize).

A more flexible way to use Faraday is to start with a Connection object. If you want to keep the same defaults, you can use this syntax:

conn=Faraday.new(:url=>'http://www.example.com')response=conn.get'/users'# GET http://www.example.com/users'

Connections can also take an options hash as a parameter or be configured by using a block. Checkout the section called Advanced middleware usage for more details about how to use this block for configurations.
Since the default middleware stack uses url_encoded middleware and default adapter, use them on building your own middleware stack.

And you can inject arbitrary data into the request using the context option:

# Anything you inject using context option will be available in the env on all middlewares
conn.getdo|req|req.url'/search'req.options.context={foo:'foo',bar:'bar'}end

Changing how parameters are serialized

Sometimes you need to send the same URL parameter multiple times with different
values. This requires manually setting the parameter encoder and can be done on
either per-connection or per-request basis.

The value of Faraday params_encoder can be any object that responds to:

encode(hash) #=> String

decode(string) #=> Hash

The encoder will affect both how query strings are processed and how POST bodies
get serialized. The default encoder is Faraday::NestedParamsEncoder.

Authentication

Basic and Token authentication are handled by Faraday::Request::BasicAuthentication and Faraday::Request::TokenAuthentication respectively. These can be added as middleware manually or through the helper methods.

Faraday.new(...) do |conn|
conn.basic_auth('username', 'password')
end
Faraday.new(...) do |conn|
conn.token_auth('authentication-token')
end

Proxy

Faraday will try to automatically infer the proxy settings from your system using URI#find_proxy.
This will retrieve them from environment variables such as http_proxy, ftp_proxy, no_proxy, etc.
If for any reason you want to disable this behaviour, you can do so by setting the global varibale ignore_env_proxy:

Writing middleware

Middleware are classes that implement a call instance method. They hook into
the request/response cycle.

defcall(request_env)# do something with the request
# request_env[:request_headers].merge!(...)
@app.call(request_env).on_completedo|response_env|# do something with the response
# response_env[:response_headers].merge!(...)
endend

It's important to do all processing of the response only in the on_complete
block. This enables middleware to work in parallel mode where requests are
asynchronous.

The env is a hash with symbol keys that contains info about the request and,
later, response. Some keys are:

Ad-hoc adapters customization

Faraday is intended to be a generic interface between your code and the adapter. However, sometimes you need to access a feature specific to one of the adapters that is not covered in Faraday's interface.

When that happens, you can pass a block when specifying the adapter to customize it. The block parameter will change based on the adapter you're using. See below for some examples.

HTTPClient

Using Faraday for testing

# It's possible to define stubbed request outside a test adapter block.
stubs=Faraday::Adapter::Test::Stubs.newdo|stub|stub.get('/tamago'){|env|[200,{},'egg']}end# You can pass stubbed request to the test adapter or define them in a block
# or a combination of the two.
test=Faraday.newdo|builder|builder.adapter:test,stubsdo|stub|stub.get('/ebi'){|env|[200,{},'shrimp']}endend# It's also possible to stub additional requests after the connection has
# been initialized. This is useful for testing.
stubs.get('/uni'){|env|[200,{},'urchin']}resp=test.get'/tamago'resp.body# => 'egg'
resp=test.get'/ebi'resp.body# => 'shrimp'
resp=test.get'/uni'resp.body# => 'urchin'
resp=test.get'/else'#=> raises "no such stub" error
# If you like, you can treat your stubs as mocks by verifying that all of
# the stubbed calls were made. NOTE that this feature is still fairly
# experimental: It will not verify the order or count of any stub, only that
# it was called once during the course of the test.
stubs.verify_stubbed_calls

Supported Ruby versions

This library aims to support and is tested against the following Ruby
implementations:

This library may inadvertently work (or seem to work) on other Ruby
implementations, however support will only be provided for the versions listed
above.

If you would like this library to support another Ruby version, you may
volunteer to be a maintainer. Being a maintainer entails making sure all tests
run and pass on that implementation. When something breaks on your
implementation, you will be responsible for providing patches in a timely
fashion. If critical issues for a particular implementation exist at the time
of a major release, support for that Ruby version may be dropped.

Contribute

Do you want to contribute to Faraday?
Open the issues page and check for the help wanted label!
But before you start coding, please read our Contributing Guide