sharpetronics/faraday
1
0
Fork 0
mirror of https://github.com/lostisland/faraday.git synced 2025-10-04 00:02:03 -04:00
Code Issues Projects Releases Wiki Activity

Improve documentation for v2 (#1353)

Browse Source
This commit is contained in:
Matt 2021-12-30 14:46:00 +00:00 committed by GitHub
parent b1165eac65
commit 1c3e27616d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 254 additions and 519 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
docs/adapters/em-http.md
View File

@ -1,72 +0,0 @@
---
layout: documentation
title: "EM-HTTP Adapter"
permalink: /adapters/em-http
hide: true
top_name: Adapters
top_link: ./
---
This Adapter uses [EventMachine](https://github.com/eventmachine/eventmachine/) and the tie in [em-http-request][src]
It can be used to make parallel requests using EventMachine.
The major difference between this and EMSynchrony is that it does not use fibers.
**Error handling and responses have a slightly different behaviour and structure in some cases. Please run thorough testing scenarios, including connection failures and SSL failures**
You will need to add em-http-request to your Gemfile:
```ruby
# Gemfile
gem 'em-http-request'
```
### Base request
```ruby
require 'faraday'
require 'em-http-request'
conn = Faraday.new(...) do |f|
# no custom options available
f.adapter :em_http
end
```
### Parallel Requests
```ruby
require 'faraday'
require 'em-http-request'
urls = Array.new(5) { 'http://127.0.0.1:3000' }
conn = Faraday::Connection.new do |builder|
builder.adapter :em_http
end
begin
conn.in_parallel do
puts "Parallel manager: #{conn.parallel_manager}"
@responses = urls.map do |url|
conn.get(url)
end
end
end
# Gather responses outside of block
puts @responses.map(&:status).join(', ')
puts @responses.map(&:status).compact.count
```
## Links
* [Gem RDoc][rdoc]
* [Gem source][src]
* [Adapter RDoc][adapter_rdoc]
* [EM-Synchrony Adapter](./em-synchrony.md)
[rdoc]: https://www.rubydoc.info/gems/em-http-request
[src]: https://github.com/igrigorik/em-http-request#readme
[adapter_rdoc]: https://www.rubydoc.info/github/lostisland/faraday/Faraday/Adapter/EMHttp

78
docs/adapters/em-synchrony.md
View File

@ -1,78 +0,0 @@
---
layout: documentation
title: "EM-Synchrony Adapter"
permalink: /adapters/em-synchrony
hide: true
top_name: Adapters
top_link: ./
---
This Adapter uses [EventMachine](https://github.com/eventmachine/eventmachine/) and the tie in [em-http-request](https://www.rubydoc.info/gems/em-http-request) in conjunction with [em-synchrony][rdoc]
It can be used to make parallel requests using EventMachine.
The key difference between this and EM-Http is that it uses fibers. For more information see igrigorik's blog posts on the matter:
- [fibers-cooperative-scheduling-in-ruby](https://www.igvita.com/2009/05/13/fibers-cooperative-scheduling-in-ruby/)
- [untangling-evented-code-with-ruby-fibers](https://www.igvita.com/2010/03/22/untangling-evented-code-with-ruby-fibers)
**Error handling and responses have a slightly different behaviour and structure in some cases. Please run thorough testing scenarios, including connection failures and SSL failures**
You will need to add em-http-request and em-synchrony to your Gemfile:
```ruby
# Gemfile
gem 'em-http-request'
gem 'em-synchrony'
```
### Base request
```ruby
require 'faraday'
require 'em-http-request'
require 'em-synchrony'
conn = Faraday.new(...) do |f|
# no custom options available
f.adapter :em_synchrony
end
```
### Parallel Requests
```ruby
require 'faraday'
require 'em-http-request'
require 'em-synchrony'
urls = Array.new(5) { 'http://127.0.0.1:3000' }
conn = Faraday::Connection.new do |builder|
builder.adapter :em_synchrony
end
begin
conn.in_parallel do
puts "Parallel manager: #{conn.parallel_manager}"
@responses = urls.map do |url|
conn.get(url)
end
end
end
# Gather responses outside of block
puts @responses.map(&:status).join(', ')
puts @responses.map(&:status).compact.count
```
## Links
* [Gem RDoc][rdoc]
* [Gem source][src]
* [Adapter RDoc][adapter_rdoc]
* [EM-HTTP Adapter](./em-http.md)
[rdoc]: https://www.rubydoc.info/gems/em-synchrony
[src]: https://github.com/igrigorik/em-synchrony
[adapter_rdoc]: https://www.rubydoc.info/github/lostisland/faraday/Faraday/Adapter/EMSynchrony

27
docs/adapters/excon.md
View File

@ -1,27 +0,0 @@
---
layout: documentation
title: "Excon Adapter"
permalink: /adapters/excon
hide: true
top_name: Adapters
top_link: ./
---
This Adapter uses the [excon][rdoc] gem to make HTTP requests.
```ruby
conn = Faraday.new(...) do |f|
# no custom options available
f.adapter :excon
end
```
## Links
* [Gem RDoc][rdoc]
* [Gem source][src]
* [Adapter RDoc][adapter_rdoc]
[rdoc]: https://www.rubydoc.info/gems/excon
[src]: https://github.com/excon/excon
[adapter_rdoc]: https://www.rubydoc.info/github/lostisland/faraday/Faraday/Adapter/Excon

30
docs/adapters/httpclient.md
View File

@ -1,30 +0,0 @@
---
layout: documentation
title: "HTTPClient Adapter"
permalink: /adapters/httpclient
hide: true
top_name: Adapters
top_link: ./
---
This Adapter uses the [httpclient][rdoc] gem to make HTTP requests.
```ruby
conn = Faraday.new(...) do |f|
f.adapter :httpclient do |client|
# yields HTTPClient
client.keep_alive_timeout = 20
client.ssl_config.timeout = 25
end
end
```
## Links
* [Gem RDoc][rdoc]
* [Gem source][src]
* [Adapter RDoc][adapter_rdoc]
[rdoc]: https://www.rubydoc.info/gems/httpclient
[src]: https://github.com/nahi/httpclient
[adapter_rdoc]: https://www.rubydoc.info/github/lostisland/faraday/Faraday/Adapter/HTTPClient

169
docs/adapters/index.md
View File

@ -11,32 +11,17 @@ HTTP clients, but can have custom implementations. Adapters can be configured
either globally or per Faraday Connection through the configuration block. either globally or per Faraday Connection through the configuration block.
{: .mt-60} {: .mt-60}
## Built-in adapters ## Fantastic adapters and where to find them
Faraday includes these adapters (but not the HTTP client libraries): With the only exception being the [Test Adapter][testing], which is for _test purposes only_,
adapters are distributed separately from Faraday.
* [Net::HTTP][net_http] _(this is the default adapter)_ They are usually available as gems, or bundled with HTTP clients.
* [Net::HTTP::Persistent][persistent]
* [Excon][excon]
* [Patron][patron]
* [EM-Synchrony][em-synchrony]
* [EM-Http][em-http]
* [HTTPClient][httpclient]
While most adapters use a common Ruby HTTP client library, adapters can also While most adapters use a common Ruby HTTP client library, adapters can also
have completely custom implementations. have completely custom implementations.
* [Test Adapter][testing] If you're just getting started you can find a list of featured adapters in [Awesome Faraday][awesome].
* Rack Adapter (link TBD) Anyone can create a Faraday adapter and distribute it. If you're interested learning more, check how to [build your own][build_adapters]!
## External adapters
Adapters are slowly being moved into their own gems, or bundled with HTTP clients.
Please refer to their documentation for usage examples.
* [Typhoeus][typhoeus]
* [HTTP.rb][faraday-http]
* [httpx][httpx]
## Ad-hoc adapters customization ## Ad-hoc adapters customization
@ -45,142 +30,6 @@ However, sometimes you need to access a feature specific to one of the adapters
When that happens, you can pass a block when specifying the adapter to customize it. 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 each adapter page for more details. The block parameter will change based on the adapter you're using. See each adapter page for more details.
## Write your own adapter [testing]: ./testing
[awesome]: https://github.com/lostisland/awesome-faraday/#adapters
Adapters have methods that can help you implement support for a new backend. [build_adapters]: ./write_your_adapter.md
This example will use a fictional HTTP backend gem called `FlorpHttp`. It doesn't
exist. Its only function is to make this example more concrete.
### An Adapter _is_ a Middleware
When you subclass `::Faraday::Adapter`, you get helpful methods defined:
```ruby
class FlorpHttp < ::Faraday::Adapter
end
```
Now, there are only two things which are actually mandatory for an adapter middleware to function:
- a `#call` implementation
- a call to `#save_response` inside `#call`, which will keep the Response around.
These are the only two things.
The rest of this text is about methods which make the authoring easier.
### Helpful method: `#build_connection`
Faraday abstracts all your backend's concrete stuff behind its user-facing API.
You take care of setting up the connection from the supplied parameters.
Example from the excon adapter: it gets an `Env` and reads its information
to instantiate an `Excon` object:
```ruby
class FlorpHttp < ::Faraday::Adapter
def build_connection(env)
opts = opts_from_env(env)
::Excon.new(env[:url].to_s, opts.merge(@connection_options))
end
end
```
The `env` contains stuff like:
- `env[:ssl]`
- `env[:request]`
There are helper to fetch timeouts: `#request_timeout(type, options)` knows
about supported timeout types, and falls back to `:timeout` if they are not set.
You can use those when building the options you need for your backend's instantiation.
So, use the information provided in `env` to instantiate your backend's connection class.
Return that instance. Now, Faraday knows how to create and reuse that connection.
### Nickname for your adapter: `.register_middleware`
You may register a nickname for your adapter. People can then refer to your adapter with that name.
You do that using `.register_middleware`, like this:
```ruby
class FlorpHttp < ::Faraday::Adapter
register_middleware(
File.expand_path('adapter', __dir__),
florp_http: [ :FlorpHttp, 'florp_http' ]
)
# ...
end
```
## Does your backend support parallel operation?
:warning: This is slightly more involved, and this section is not fully formed.
Vague example, excerpted from [the test suite about parallel requests](https://github.com/lostisland/faraday/blob/master/spec/support/shared_examples/request_method.rb#L179)
```ruby
response_1 = nil
response_2 = nil
conn.in_parallel do
response_1 = conn.get('/about')
response_2 = conn.get('/products')
end
puts response_1.status
puts response_2.status
```
First, in your class definition, you can tell Faraday that your backend supports parallel operation:
```ruby
class FlorpHttp < ::Faraday::Adapter
dependency do
require 'florp_http'
end
self.supports_parallel = true
end
```
Then, implement a method which returns a ParallelManager:
```ruby
class FlorpHttp < ::Faraday::Adapter
dependency do
require 'florp_http'
end
self.supports_parallel = true
def self.setup_parallel_manager(_options = nil)
FlorpParallelManager.new # NB: we will need to define this
end
end
class FlorpParallelManager
def add(request, method, *args, &block)
# Collect the requests
end
def run
# Process the requests
end
end
```
Compare to the finished example [em-synchrony](https://github.com/lostisland/faraday/blob/master/lib/faraday/adapter/em_synchrony.rb) and its [ParallelManager implementation](https://github.com/lostisland/faraday/blob/master/lib/faraday/adapter/em_synchrony/parallel_manager.rb).
[net_http]: ./net-http
[persistent]: ./net-http-persistent
[excon]: ./excon
[patron]: ./patron
[em-synchrony]: ./em-synchrony
[em-http]: ./em-http
[httpclient]: ./httpclient
[typhoeus]: https://github.com/typhoeus/typhoeus/blob/master/lib/typhoeus/adapters/faraday.rb
[faraday-http]: https://github.com/lostisland/faraday-http
[testing]: ./testing
[httpx]: https://honeyryderchuck.gitlab.io/httpx/wiki/Faraday-Adapter

31
docs/adapters/net_http.md
View File

@ -1,31 +0,0 @@
---
layout: documentation
title: "Net::HTTP Adapter"
permalink: /adapters/net-http
hide: true
top_name: Adapters
top_link: ./
---
This Adapter uses the [`Net::HTTP`][rdoc] client from the Ruby standard library to make
HTTP requests.
```ruby
conn = Faraday.new(...) do |f|
f.adapter :net_http do |http|
# yields Net::HTTP
http.idle_timeout = 100
http.verify_callback = lambda do |preverify, cert_store|
# do something here...
end
end
end
```
## Links
* [Net::HTTP RDoc][rdoc]
* [Adapter RDoc][adapter_rdoc]
[rdoc]: http://ruby-doc.org/stdlib/libdoc/net/http/rdoc/Net/HTTP.html
[adapter_rdoc]: https://www.rubydoc.info/github/lostisland/faraday/Faraday/Adapter/NetHttp

29
docs/adapters/net_http_persistent.md
View File

@ -1,29 +0,0 @@
---
layout: documentation
title: "Net::HTTP::Persistent Adapter"
permalink: /adapters/net-http-persistent
hide: true
top_name: Adapters
top_link: ./
---
This Adapter uses the [net-http-persistent][rdoc] gem to make HTTP requests.
```ruby
conn = Faraday.new(...) do |f|
f.adapter :net_http_persistent, pool_size: 5 do |http|
# yields Net::HTTP::Persistent
http.idle_timeout = 100
end
end
```
## Links
* [Gem RDoc][rdoc]
* [Gem source][src]
* [Adapter RDoc][adapter_rdoc]
[rdoc]: https://www.rubydoc.info/gems/net-http-persistent
[src]: https://github.com/drbrain/net-http-persistent
[adapter_rdoc]: https://www.rubydoc.info/github/lostisland/faraday/Faraday/Adapter/NetHttpPersistent

29
docs/adapters/patron.md
View File

@ -1,29 +0,0 @@
---
layout: documentation
title: "Patron Adapter"
permalink: /adapters/patron
hide: true
top_name: Adapters
top_link: ./
---
This Adapter uses the [patron][rdoc] gem to make HTTP requests.
```ruby
conn = Faraday.new(...) do |f|
f.adapter :patron do |session|
# yields Patron::Session
session.max_redirects = 10
end
end
```
## Links
* [Gem RDoc][rdoc]
* [Gem source][src]
* [Adapter RDoc][adapter_rdoc]
[rdoc]: https://www.rubydoc.info/gems/patron
[src]: https://github.com/toland/patron
[adapter_rdoc]: https://www.rubydoc.info/github/lostisland/faraday/Faraday/Adapter/Patron

171
docs/adapters/write_your_adapter.md Normal file
View File

@ -0,0 +1,171 @@
---
layout: documentation
title: "Write your own adapter"
permalink: /adapters/write_your_adapter
hide: true
order: 2
---
Adapters have methods that can help you implement support for a new backend.
This example will use a fictional HTTP backend gem called `FlorpHttp`. It doesn't
exist. Its only function is to make this example more concrete.
### An Adapter _is_ a Middleware
When you subclass `::Faraday::Adapter`, you get helpful methods defined:
```ruby
class FlorpHttp < ::Faraday::Adapter
end
```
Now, there are only two things which are actually mandatory for an adapter middleware to function:
- a `#call` implementation
- a call to `#save_response` inside `#call`, which will keep the Response around.
These are the only two things.
The rest of this text is about methods which make the authoring easier.
### Helpful method: `#build_connection`
Faraday abstracts all your backend's concrete stuff behind its user-facing API.
You take care of setting up the connection from the supplied parameters.
Example from the excon adapter: it gets an `Env` and reads its information
to instantiate an `Excon` object:
```ruby
class FlorpHttp < ::Faraday::Adapter
def build_connection(env)
opts = opts_from_env(env)
::Excon.new(env[:url].to_s, opts.merge(@connection_options))
end
end
```
The `env` contains stuff like:
- `env[:ssl]`
- `env[:request]`
There are helper methods to fetch timeouts: `#request_timeout(type, options)` knows
about supported timeout types, and falls back to `:timeout` if they are not set.
You can use those when building the options you need for your backend's instantiation.
So, use the information provided in `env` to instantiate your backend's connection class.
Return that instance. Now, Faraday knows how to create and reuse that connection.
### Connection options and configuration block
Users of your adapter have two main ways of configuring it:
* connection options: these can be passed to your adapter initializer and are automatically stored into an instance variable `@connection_options`.
* configuration block: this can also be provided to your adapter initializer and it's stored into an instance variable `@config_block`.
Both of these are automatically managed by `Faraday::Adapter#initialize`, so remember to call it with `super` if you create an `initialize` method in your adapter.
You can then use them in your adapter code as you wish, since they're pretty flexible.
Below is an example of how they can be used:
```ruby
# You can use @connection_options and @config_block in your adapter code
class FlorpHttp < ::Faraday::Adapter
def call(env)
# `connection` internally calls `build_connection` and yields the result
connection do |conn|
# perform the request using configured `conn`
end
end
def build_connection(env)
conn = FlorpHttp::Client.new(pool_size: @connection_options[:pool_size] || 10)
@config_block&.call(conn)
conn
end
end
# Then your users can provide them when initializing the connection
Faraday.new(...) do |f|
# ...
# in this example, { pool_size: 5 } will be provided as `connection_options`
f.adapter :florp_http, pool_size: 5 do |client|
# this block is useful to set properties unique to HTTP clients that are not
# manageable through the Faraday API
client.some_fancy_florp_http_property = 10
end
end
```
### Nickname for your adapter: `.register_middleware`
You may register a nickname for your adapter. People can then refer to your adapter with that name.
You do that using `.register_middleware`, like this:
```ruby
class FlorpHttp < ::Faraday::Adapter
# ...
end
Faraday::Adapter.register_middleware(florp_http: FlorpHttp)
```
## Does your backend support parallel operation?
:warning: This is slightly more involved, and this section is not fully formed.
Vague example, excerpted from [the test suite about parallel requests](https://github.com/lostisland/faraday/blob/master/spec/support/shared_examples/request_method.rb#L179)
```ruby
response_1 = nil
response_2 = nil
conn.in_parallel do
response_1 = conn.get('/about')
response_2 = conn.get('/products')
end
puts response_1.status
puts response_2.status
```
First, in your class definition, you can tell Faraday that your backend supports parallel operation:
```ruby
class FlorpHttp < ::Faraday::Adapter
dependency do
require 'florp_http'
end
self.supports_parallel = true
end
```
Then, implement a method which returns a ParallelManager:
```ruby
class FlorpHttp < ::Faraday::Adapter
dependency do
require 'florp_http'
end
self.supports_parallel = true
def self.setup_parallel_manager(_options = nil)
FlorpParallelManager.new # NB: we will need to define this
end
end
class FlorpParallelManager
def add(request, method, *args, &block)
# Collect the requests
end
def run
# Process the requests
end
end
```
Compare to the finished example [em-synchrony](https://github.com/lostisland/faraday-em_synchrony/blob/main/lib/faraday/adapter/em_synchrony.rb)
and its [ParallelManager implementation](https://github.com/lostisland/faraday-em_synchrony/blob/main/lib/faraday/adapter/em_synchrony/parallel_manager.rb).

131
docs/usage/index.md
View File

@ -8,17 +8,29 @@ order: 1
--- ---
Let's fetch the home page for the wonderful Let's fetch the home page for the wonderful
[httpbingo.org](https://httpbingo.org) service. Make a simple `GET` request by [httpbingo.org](https://httpbingo.org) service.
requiring the Faraday gem and using `Faraday.get`:
First of all, you need to tell Faraday which [`adapter`](../adapters) you wish to use.
Adapters are responsible for actually executing HTTP requests.
There are many different adapters you can choose from.
Just pick the one you like and install it, or add it to your project Gemfile.
You might want to use Faraday with the `Net::HTTP` adapter, for example.
[Learn more about Adapters](../adapters).
Remember you'll need to install the corresponding adapter gem before you'll be able to use it.
```ruby ```ruby
require 'faraday' require 'faraday/net_http'
Faraday.default_adapter = :net_http
response = Faraday.get 'http://httpbingo.org'
``` ```
This returns a `Faraday::Response` object with the response status, headers, and Next, you can make a simple `GET` request using `Faraday.get`:
body.
```ruby
response = Faraday.get('http://httpbingo.org')
```
This returns a `Faraday::Response` object with the response status, headers, and body.
```ruby ```ruby
response.status response.status
@ -31,10 +43,36 @@ response.body
# => "<!DOCTYPE html><html> ... # => "<!DOCTYPE html><html> ...
``` ```
### GET ### Faraday Connection
Faraday supports the following HTTP verbs that typically don't include a request The recommended way to use Faraday, especially when integrating to 3rd party services and API, is to create
body: a `Faraday::Connection`. The connection object can be configured with things like:
- default request headers & query parameters
- network settings like proxy or timeout
- common URL base path
- Faraday adapter & middleware (see below)
Create a `Faraday::Connection` by calling `Faraday.new`. You can then call each HTTP verb
(`get`, `post`, ...) on your `Faraday::Connection` to perform a request:
```ruby
conn = Faraday.new(
url: 'http://httpbingo.org',
params: {param: '1'},
headers: {'Content-Type' => 'application/json'}
)
response = conn.post('/post') do |req|
req.params['limit'] = 100
req.body = {query: 'chunky bacon'}.to_json
end
# => POST http://httpbingo.org/post?param=1&limit=100
```
### GET, HEAD, DELETE, TRACE
Faraday supports the following HTTP verbs that typically don't include a request body:
- `get(url, params = nil, headers = nil)` - `get(url, params = nil, headers = nil)`
- `head(url, params = nil, headers = nil)` - `head(url, params = nil, headers = nil)`
@ -44,12 +82,11 @@ body:
You can specify URI query parameters and HTTP headers when making a request. You can specify URI query parameters and HTTP headers when making a request.
```ruby ```ruby
url = 'http://httpbingo.org/get' response = conn.get('get', { boom: 'zap' }, { 'User-Agent' => 'myapp' })
response = Faraday.get(url, {boom: 'zap'}, {'User-Agent' => 'myapp'})
# => GET http://httpbingo.org/get?boom=zap # => GET http://httpbingo.org/get?boom=zap
``` ```
### POST ### POST, PUT, PATCH
Faraday also supports HTTP verbs with bodies. Instead of query parameters, these Faraday also supports HTTP verbs with bodies. Instead of query parameters, these
accept a request body: accept a request body:
@ -59,13 +96,11 @@ accept a request body:
- `patch(url, body = nil, headers = nil)` - `patch(url, body = nil, headers = nil)`
```ruby ```ruby
url = 'http://httpbingo.org/post'
# POST 'application/x-www-form-urlencoded' content # POST 'application/x-www-form-urlencoded' content
response = Faraday.post(url, "boom=zap") response = conn.post('post', 'boom=zap')
# POST JSON content # POST JSON content
response = Faraday.post(url, '{"boom": "zap"}', response = conn.post('post', '{"boom": "zap"}',
"Content-Type" => "application/json") "Content-Type" => "application/json")
``` ```
@ -75,8 +110,7 @@ Faraday will automatically convert key/value hashes into proper form bodies.
```ruby ```ruby
# POST 'application/x-www-form-urlencoded' content # POST 'application/x-www-form-urlencoded' content
url = 'http://httpbingo.org/post' response = conn.post('post', boom: 'zap')
response = Faraday.post(url, boom: 'zap')
# => POST 'boom=zap' to http://httpbingo.org/post # => POST 'boom=zap' to http://httpbingo.org/post
``` ```
@ -93,7 +127,7 @@ This example shows a hypothetical search endpoint that accepts a JSON request
body as the actual search query. body as the actual search query.
```ruby ```ruby
response = Faraday.post('http://httpbingo.org/post') do |req| response = conn.post('post') do |req|
req.params['limit'] = 100 req.params['limit'] = 100
req.headers['Content-Type'] = 'application/json' req.headers['Content-Type'] = 'application/json'
req.body = {query: 'chunky bacon'}.to_json req.body = {query: 'chunky bacon'}.to_json
@ -101,40 +135,6 @@ end
# => POST http://httpbingo.org/post?limit=100 # => POST http://httpbingo.org/post?limit=100
``` ```
### Customizing Faraday::Connection
You may want to create a `Faraday::Connection` to setup a common config for
multiple requests. The connection object can be configured with things like:
- default request headers & query parameters
- network settings like proxy or timeout
- common URL base path
- Faraday adapter & middleware (see below)
Create a `Faraday::Connection` by calling `Faraday.new`. The HTTP verbs
described above (`get`, `post`, ...) are `Faraday::Connection` methods:
```ruby
conn = Faraday.new(
url: 'http://httpbingo.org',
params: {param: '1'},
headers: {'Content-Type' => 'application/json'}
)
response = conn.post('/post') do |req|
req.params['limit'] = 100
req.body = {query: 'chunky bacon'}.to_json
end
# => POST http://httpbingo.org/post?param=1&limit=100
```
### Adapters
Adapters are responsible for actually executing HTTP requests. The default
adapter uses Ruby's `Net::HTTP`, but there are many different adapters
available. You might want to use Faraday with the Typhoeus adapter, for example.
[Learn more about Adapters](../adapters).
### Middleware ### Middleware
Under the hood, Faraday uses a Rack-inspired middleware stack for making Under the hood, Faraday uses a Rack-inspired middleware stack for making
@ -158,13 +158,20 @@ and add the correct middleware in a block. For example:
```ruby ```ruby
require 'faraday_middleware' require 'faraday_middleware'
conn = Faraday.new do |f| conn = Faraday.new('http://httpbingo.org') do |f|
f.request :json # encode req bodies as JSON f.request :json # encode req bodies as JSON and automatically set the Content-Type header
f.request :retry # retry transient failures f.request :retry # retry transient failures
f.response :follow_redirects # follow redirects f.response :follow_redirects # follow redirects (3xx HTTP response codes)
f.response :json # decode response bodies as JSON f.response :json # decode response bodies as JSON
f.adapter :net_http # adds the adapter to the connection, defaults to `Faraday.default_adapter`
end end
response = conn.get("http://httpbingo.org/get")
# Sends a GET request with JSON body that will automatically retry in case of failure
# and follow 3xx redirects.
response = conn.get('get', boom: 'zap')
# response body is automatically decoded from JSON to a Ruby hash
response.body['args'] #=> {"boom"=>["zap"]}
``` ```
#### Default Connection, Default Middleware #### Default Connection, Default Middleware
@ -173,10 +180,10 @@ Remember how we said that Faraday will automatically encode key/value hash
bodies into form bodies? Internally, the top level shortcut methods bodies into form bodies? Internally, the top level shortcut methods
`Faraday.get`, `post`, etc. use a simple default `Faraday::Connection`. The only `Faraday.get`, `post`, etc. use a simple default `Faraday::Connection`. The only
middleware used for the default connection is `:url_encoded`, which encodes middleware used for the default connection is `:url_encoded`, which encodes
those form hashes. those form hashes, and the `default_adapter`.
Note that if you create your own connection with middleware, it won't encode Note that if you create your own connection with middleware, it won't encode
form bodies unless you too include the `:url_encoded` middleware! form bodies unless you too include the [`:url_encoded`](encoding) middleware!
[encoding]: ../middleware/url-encoded [encoding]: ../middleware/url-encoded
[multipart]: ../middleware/multipart [multipart]: ../middleware/multipart

6
docs/usage/streaming.md
View File

@ -34,4 +34,8 @@ end
streamed.join streamed.join
``` ```
The `on_data` streaming is currently only supported by the `Net::HTTP` adapter. The `on_data` streaming is currently only supported by some adapters.
To see which ones, please refer to [Awesome Faraday][awesome] comparative table or check the adapter documentation.
[awesome]: https://github.com/lostisland/awesome-faraday/#adapters