faraday/docs/introduction/basics.md

layout	title	permalink	hide
page	The Basics	/introduction/basics	true

A GET request can be performed by calling the .get class method:

response = Faraday.get 'http://sushi.com/nigiri/sake.json'

This works if you don't need to set up anything; you can roll with the default middleware stack and default adapter (see Faraday::RackBuilder#initialize).

The Connection Object

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.sushi.com')

Connections can also take an options hash as a parameter, or be configured with a block. Check out the Middleware page for more details about how to use this block for configurations. Since the default middleware stack uses the url_encoded middleware and default adapter, use them on building your own middleware stack.

conn = Faraday.new(url: 'http://sushi.com') do |faraday|
  # form-encode POST params
  faraday.request :url_encoded
  # log requests and responses to $stdout
  faraday.response :logger
  # make requests with Net::HTTP
  faraday.adapter Faraday.default_adapter
end

Once you have the connection object, use it to make HTTP requests. You can pass parameters to it in a few different ways:

conn = Faraday.new(url: 'http://sushi.com/nigiri')

## GET ##

response = conn.get 'sake.json'
# => GET http://sushi.com/nigiri/sake.json

# Using an absolute path overrides the path from the connection initializer
response = conn.get '/maki/platters.json'
# => GET http://sushi.com/maki/platters.json
 
# You can then access the response body
response.body

# Path can also be empty. Parameters can be provided as a hash.
conn.get '', { name: 'Maguro' }
# => GET http://sushi.com/nigiri?name=Maguro

conn.get do |req|
  req.url '/search', page: 2
  req.params['limit'] = 100
end
# => GET http://sushi.com/search?limit=100&page=2

## POST ##

# Parameters for POST requests are automatically put in the body as
# www-form-urlencoded.
conn.post '', { name: 'Maguro' }
# => POST "name=maguro" to http://sushi.com/nigiri

# To post as JSON instead of www-form-urlencoded, set the request header
conn.post do |req|
  req.url ''
  req.headers['Content-Type'] = 'application/json'
  req.body = '{ "name": "Unagi" }'
end
# => POST "{ "name": "Unagi" }" to http://sushi.com/nigiri