= 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

Copyright (c) 2009 rick. See LICENSE for details.