Migrating from rest-client to Faraday¶ ↑

The rest-client gem is in maintenance mode, and developers are encouraged to migrate to actively maintained alternatives like {faraday}. This guide highlights common usage patterns in rest-client and how to migrate them to faraday.

Quick Comparison¶ ↑

Installation¶ ↑

In your Gemfile, replace rest-client with:

gem "faraday"

Then run:

bundle install

Basic HTTP Requests¶ ↑

GET request¶ ↑

rest-client:

RestClient.get("https://httpbingo.org/get")

faraday:

Faraday.get("https://httpbingo.org/get")

GET with Params¶ ↑

rest-client:

RestClient.get("https://httpbingo.org/get", params: { id: 1, foo: "bar" })

faraday:

Faraday.get("https://httpbingo.org/get", { id: 1, foo: "bar" })

POST Requests¶ ↑

rest-client:

RestClient.post("https://httpbingo.org/post", { foo: "bar" })

faraday:

Faraday.post("https://httpbingo.org/post", { foo: "bar" })

Sending JSON¶ ↑

rest-client:

RestClient.post("https://httpbingo.org/post", { foo: "bar" }.to_json, content_type: :json)

faraday (manual):

Faraday.post("https://httpbingo.org/post", { foo: "bar" }.to_json, { 'Content-Type' => 'application/json' })

faraday (with middleware):

conn = Faraday.new(url: "https://httpbingo.org") do |f|
  f.request :json            # encode request body as JSON and set Content-Type
  f.response :json           # parse response body as JSON
end

conn.post("/post", { foo: "bar" })

Handling Responses¶ ↑

rest-client:

response = RestClient.get("https://httpbingo.org/headers")
response.code    # => 200
response.body    # => "..."
response.headers # => { content_type: "application/json", ... }

faraday:

notice headers Hash keys are stringified, not symbolized like in rest-client

response = Faraday.get("https://httpbingo.org/headers")
response.status     # => 200
response.body       # => "..."
response.headers    # => { "content-type" => "application/json", ... }

Error Handling¶ ↑

rest-client:

begin
  RestClient.get("https://httpbingo.org/status/404")
rescue RestClient::NotFound => e
  puts e.response.code  # 404
end

faraday:

By default, Faraday does not raise exceptions for HTTP errors (like 404 or 500); it simply returns the response. If you want exceptions to be raised on HTTP error responses, include the :raise_error middleware.

With :raise_error, Faraday will raise Faraday::ResourceNotFound for 404s and other exceptions for other 4xx/5xx responses.

See also:

• Dealing with Errors

• Raising Errors

conn = Faraday.new(url: "https://httpbingo.org") do |f|
  f.response :raise_error
end

begin
  conn.get("/status/404")
rescue Faraday::ResourceNotFound => e
  puts e.response[:status]  # 404
end

Advanced Request Configuration¶ ↑

rest-client:

RestClient::Request.execute(method: :get, url: "https://httpbingo.org/get", timeout: 10)

faraday:

conn = Faraday.new(url: "https://httpbingo.org", request: { timeout: 10 })
conn.get("/get")

Headers¶ ↑

rest-client:

RestClient.get("https://httpbingo.org/headers", { Authorization: "Bearer token" })

faraday:

Notice headers Hash expects stringified keys.

Faraday.get("https://httpbingo.org/headers", nil, { "Authorization" => "Bearer token" })

Redirects¶ ↑

rest-client: Automatically follows GET/HEAD redirects by default.

faraday: Use the follow_redirects middleware (not included by default):

require "faraday/follow_redirects"

conn = Faraday.new(url: "https://httpbingo.org") do |f|
  f.response :follow_redirects
end