Skip to content
Browse files

improve Readme

  • Loading branch information...
1 parent ac1b537 commit ffa01e253aa053e7516adc25c57f64919bd1ef55 @mislav mislav committed Jun 19, 2012
Showing with 72 additions and 49 deletions.
  1. +72 −49 README.md
View
121 README.md
@@ -6,35 +6,30 @@ processing the request/response cycle.
Faraday supports these adapters:
-* Net/HTTP
-* Excon
-* Typhoeus
-* Patron
-* EventMachine
+* Net::HTTP
+* [Excon][]
+* [Typhoeus][]
+* [Patron][]
+* [EventMachine][]
It also includes a Rack adapter for hitting loaded Rack applications through
Rack::Test, and a Test adapter for stubbing requests by hand.
## Usage
```ruby
-conn = Faraday.new(:url => 'http://sushi.com') do |builder|
- builder.use Faraday::Request::UrlEncoded # convert request params as "www-form-urlencoded"
- builder.use Faraday::Response::Logger # log the request to STDOUT
- builder.use Faraday::Adapter::NetHttp # make http requests with Net::HTTP
-
- # or, use shortcuts:
- builder.request :url_encoded
- builder.response :logger
- builder.adapter :net_http
+conn = Faraday.new(:url => 'http://sushi.com') do |faraday|
+ faraday.request :url_encoded # form-encode POST params
+ faraday.response :logger # log requests to STDOUT
+ faraday.adapter Faraday.default_adapter # make requests with Net::HTTP
end
## GET ##
response = conn.get '/nigiri/sake.json' # GET http://sushi.com/nigiri/sake.json
response.body
-conn.get '/nigiri', { :name => 'Maguro' } # GET /nigiri?name=Maguro
+conn.get '/nigiri', { :name => 'Maguro' } # GET /nigiri?name=Maguro
conn.get do |req| # GET http://sushi.com/search?page=2&limit=100
req.url '/search', :page => 2
@@ -52,7 +47,7 @@ conn.post do |req|
req.body = '{ "name": "Unagi" }'
end
-## Options ##
+## Per-request options ##
conn.get do |req|
req.url '/search'
@@ -61,25 +56,26 @@ conn.get do |req|
end
```
-If you're ready to roll with just the bare minimum:
+If you don't need to set up anything, you can roll with just the bare minimum:
```ruby
-# default stack (net/http), no extra middleware:
+# using the default stack:
response = Faraday.get 'http://sushi.com/nigiri/sake.json'
```
## Advanced middleware usage
+
The order in which middleware is stacked is important. Like with Rack, the
first middleware on the list wraps all others, while the last middleware is the
-innermost one, so that's usually the adapter.
+innermost one, so that must be the adapter.
```ruby
-conn = Faraday.new(:url => 'http://sushi.com') do |builder|
+Faraday.new(...) do |conn|
# POST/PUT params encoders:
- builder.request :multipart
- builder.request :url_encoded
+ conn.request :multipart
+ conn.request :url_encoded
- builder.adapter :net_http
+ conn.adapter :net_http
end
```
@@ -97,18 +93,17 @@ process it.
Examples:
```ruby
-payload = { :name => 'Maguro' }
-
# uploading a file:
-payload = { :profile_pic => Faraday::UploadIO.new('avatar.jpg', 'image/jpeg') }
+payload[:profile_pic] = Faraday::UploadIO.new('/path/to/avatar.jpg', 'image/jpeg')
# "Multipart" middleware detects files and encodes with "multipart/form-data":
conn.put '/profile', payload
```
## Writing middleware
-Middleware are classes that respond to `call()`. They wrap the request/response
-cycle.
+
+Middleware are classes that implement a `call` instance method. They hook into
+the request/response cycle.
```ruby
def call(env)
@@ -140,7 +135,7 @@ later, response. Some keys are:
:response_headers
```
-## Testing
+## Using Faraday for testing
```ruby
# It's possible to define stubbed request outside a test adapter block.
@@ -176,36 +171,51 @@ stubs.verify_stubbed_calls
```
## TODO
+
* support streaming requests/responses
* better stubbing API
-## Note on Patches/Pull Requests
-1. Fork the project.
-2. Make your feature addition or bug fix.
-3. Add tests for it. This is important so I don't break it in a future version
- unintentionally.
-4. 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)
-5. Send us a pull request. Bonus points for topic branches.
+## Contributing
+
+You can run the test suite against a live server by running `script/test`. It
+automatically starts a test server in background. Only tests in
+`test/adapters/*_test.rb` require a server, though.
+
+``` sh
+# run the whole suite
+$ script/server
+
+# run only specific files
+$ script/server excon typhoeus
+```
+
+We will accept middleware that:
+
+1. is useful to a broader audience, but can be implemented relatively
+ simple; and
+2. which isn't already present in [faraday_middleware][] project.
+
+We will accept adapters that:
+
+1. support SSL & streaming;
+1. are proven and may have better performance than existing ones; or
+2. if they have features not present in included adapters.
We are pushing towards a 1.0 release, when we will have to follow [Semantic
-Versioning](http://semver.org/). If your patch includes changes to break
-compatiblitity, note that so we can add it to the [Changelog](https://github.com/technoweenie/faraday/wiki/Changelog).
+Versioning][semver]. If your patch includes changes to break compatiblitity,
+note that so we can add it to the [Changelog][].
+
+## Supported Ruby versions
-## Supported Ruby Versions
This library aims to support and is [tested against][travis] the following Ruby
implementations:
-* Ruby 1.8.7
-* Ruby 1.9.2
-* Ruby 1.9.3
-* JRuby[]
+* MRI 1.8.7
+* MRI 1.9.2
+* MRI 1.9.3
+* [JRuby][]
* [Rubinius][]
-[jruby]: http://jruby.org/
-[rubinius]: http://rubini.us/
-
If something doesn't work on one of these interpreters, it should be considered
a bug.
@@ -221,7 +231,20 @@ timely fashion. If critical issues for a particular implementation exist at the
time of a major release, support for that Ruby version may be dropped.
## Copyright
+
Copyright (c) 2009-2012 [Rick Olson](mailto:technoweenie@gmail.com), zack hobson.
See [LICENSE][] for details.
-[license]: https://github.com/technoweenie/faraday/blob/master/LICENSE.md
+
+ [license]: https://github.com/technoweenie/faraday/blob/master/LICENSE.md
+ [travis]: http://travis-ci.org/technoweenie/faraday
+ [jruby]: http://jruby.org/
+ [rubinius]: http://rubini.us/
+ [semver]: http://semver.org/
+ [changelog]: https://github.com/technoweenie/faraday/wiki/Changelog
+ [excon]: https://github.com/geemus/excon#readme
+ [typhoeus]: https://github.com/typhoeus/typhoeus#readme
+ [patron]: http://toland.github.com/patron/
+
+ [eventmachine]: https://github.com/igrigorik/em-http-request#readme
+ [faraday_middleware]: https://github.com/pengwynn/faraday_middleware/wiki

0 comments on commit ffa01e2

Please sign in to comment.
Something went wrong with that request. Please try again.