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:

# customize your own TestConnection or just use Faraday::TestConnection
class TestConnection < Faraday::Connection
  include Faraday::Adapter::MockRequest
end

conn = TestConnection.new do |stub|
  # response mimics a rack response
  stub.get('/hello.json') { [200, {}, '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

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

Copyright © 2009 rick. See LICENSE for details.