faraday

Experiments in a REST API lib

Super alpha! Don’t use it if you mind throwing away all the code when I change the API on a whim.

This mess is gonna get raw, like sushi. So, haters to the left.

Usage

# uses Net/HTTP, no response parsing
conn = Faraday::Connection.new("http://sushi.com")
conn.extend Faraday::Adapter::NetHttp
resp = conn.get("/sake.json")
resp.body # => %({"name":"Sake"})

# uses Net/HTTP, Yajl parsing
conn = Faraday::Connection.new("http://sushi.com")
conn.extend Faraday::Adapter::NetHttp
conn.response_class = Faraday::Response::YajlResponse
resp = conn.get("/sake.json")
resp.body # => {"name": "Sake"}

# uses Typhoeus, no response parsing
conn = Faraday::Connection.new("http://sushi.com")
conn.extend Faraday::Adapter::Typhoeus
resp = conn.get("/sake.json")
resp.body # => %({"name":"Sake"})

# uses Typhoeus, Yajl parsing, performs requests in parallel
conn = Faraday::Connection.new("http://sushi.com")
conn.extend Faraday::Adapter::Typhoeus
conn.response_class = Faraday::Response::YajlResponse
resp1, resp2 = nil, nil
conn.in_parallel do
  resp1 = conn.get("/sake.json")
  resp2 = conn.get("/unagi.json")

  # requests have not been made yet
  resp1.body # => nil
  resp2.body # => nil
end
resp1.body # => {"name": "Sake"}
resp2.body # => {"name": "Unagi"}

Testing

Yajl is needed for tests :(
Live Sinatra server is required for tests: ‘ruby test/live_server.rb` to start it.

Writing tests based on faraday

Using the MockRequest connection adapter you can implement your own test connection class:

class TestConnection < Faraday::Connection
  extend Faraday::Adapter::MockRequest
end

conn = TestConnection.new do |stub|
  stub.get('/hello.json', { 'hi world' }
end
resp = conn.get '/hello.json'
resp.body                     # => 'hi world'
resp = conn.get '/whatever'   # => <not stubbed, raises connection error>

TODO

other HTTP methods besides just GET
gracefully skip tests for Yajl and other optional libraries if they don’t exist.
gracefully skip live http server tests if the sinatra server is not running.
use Typhoeus’ request mocking facilities in the Typhoeus adapter test
lots of other crap

Note on Patches/Pull Requests