sharpetronics/faraday
1
0
Fork 0
mirror of https://github.com/lostisland/faraday.git synced 2025-10-06 00:03:36 -04:00
Code Issues Projects Releases Wiki Activity

improve Readme

Browse Source
This commit is contained in:
Mislav Marohnić 2012-06-19 12:32:01 +02:00
parent ac1b537f49
commit ffa01e253a
1 changed files with 72 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
README.md
View File

@ -6,11 +6,11 @@ processing the request/response cycle.
Faraday supports these adapters: Faraday supports these adapters:
* Net/HTTP * Net::HTTP
* Excon * [Excon][]
* Typhoeus * [Typhoeus][]
* Patron * [Patron][]
* EventMachine * [EventMachine][]
It also includes a Rack adapter for hitting loaded Rack applications through It also includes a Rack adapter for hitting loaded Rack applications through
Rack::Test, and a Test adapter for stubbing requests by hand. Rack::Test, and a Test adapter for stubbing requests by hand.
@ -18,15 +18,10 @@ Rack::Test, and a Test adapter for stubbing requests by hand.
## Usage ## Usage
```ruby ```ruby
conn = Faraday.new(:url => 'http://sushi.com') do |builder| conn = Faraday.new(:url => 'http://sushi.com') do |faraday|
builder.use Faraday::Request::UrlEncoded # convert request params as "www-form-urlencoded" faraday.request :url_encoded # form-encode POST params
builder.use Faraday::Response::Logger # log the request to STDOUT faraday.response :logger # log requests to STDOUT
builder.use Faraday::Adapter::NetHttp # make http requests with Net::HTTP faraday.adapter Faraday.default_adapter # make requests with Net::HTTP
# or, use shortcuts:
builder.request :url_encoded
builder.response :logger
builder.adapter :net_http
end end
## GET ## ## GET ##
@ -34,7 +29,7 @@ end
response = conn.get '/nigiri/sake.json' # GET http://sushi.com/nigiri/sake.json response = conn.get '/nigiri/sake.json' # GET http://sushi.com/nigiri/sake.json
response.body 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 conn.get do |req| # GET http://sushi.com/search?page=2&limit=100
req.url '/search', :page => 2 req.url '/search', :page => 2
@ -52,7 +47,7 @@ conn.post do |req|
req.body = '{ "name": "Unagi" }' req.body = '{ "name": "Unagi" }'
end end
## Options ## ## Per-request options ##
conn.get do |req| conn.get do |req|
req.url '/search' req.url '/search'
@ -61,25 +56,26 @@ conn.get do |req|
end 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 ```ruby
# default stack (net/http), no extra middleware: # using the default stack:
response = Faraday.get 'http://sushi.com/nigiri/sake.json' response = Faraday.get 'http://sushi.com/nigiri/sake.json'
``` ```
## Advanced middleware usage ## Advanced middleware usage
The order in which middleware is stacked is important. Like with Rack, the 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 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 ```ruby
conn = Faraday.new(:url => 'http://sushi.com') do |builder| Faraday.new(...) do |conn|
# POST/PUT params encoders: # POST/PUT params encoders:
builder.request :multipart conn.request :multipart
builder.request :url_encoded conn.request :url_encoded
builder.adapter :net_http conn.adapter :net_http
end end
``` ```
@ -97,18 +93,17 @@ process it.
Examples: Examples:
```ruby ```ruby
payload = { :name => 'Maguro' }
# uploading a file: # 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": # "Multipart" middleware detects files and encodes with "multipart/form-data":
conn.put '/profile', payload conn.put '/profile', payload
``` ```
## Writing middleware ## 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 ```ruby
def call(env) def call(env)
@ -140,7 +135,7 @@ later, response. Some keys are:
:response_headers :response_headers
``` ```
## Testing ## Using Faraday for testing
```ruby ```ruby
# It's possible to define stubbed request outside a test adapter block. # It's possible to define stubbed request outside a test adapter block.
@ -176,36 +171,51 @@ stubs.verify_stubbed_calls
``` ```
## TODO ## TODO
* support streaming requests/responses * support streaming requests/responses
* better stubbing API * better stubbing API
## Note on Patches/Pull Requests ## Contributing
1. Fork the project.
2. Make your feature addition or bug fix. You can run the test suite against a live server by running `script/test`. It
3. Add tests for it. This is important so I don't break it in a future version automatically starts a test server in background. Only tests in
unintentionally. `test/adapters/*_test.rb` require a server, though.
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 ``` sh
ignore when I pull) # run the whole suite
5. Send us a pull request. Bonus points for topic branches. $ 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 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 Versioning][semver]. If your patch includes changes to break compatiblitity,
compatiblitity, note that so we can add it to the [Changelog](https://github.com/technoweenie/faraday/wiki/Changelog). 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 This library aims to support and is [tested against][travis] the following Ruby
implementations: implementations:
* Ruby 1.8.7 * MRI 1.8.7
* Ruby 1.9.2 * MRI 1.9.2
* Ruby 1.9.3 * MRI 1.9.3
* JRuby[] * [JRuby][]
* [Rubinius][] * [Rubinius][]
[jruby]: http://jruby.org/
[rubinius]: http://rubini.us/
If something doesn't work on one of these interpreters, it should be considered If something doesn't work on one of these interpreters, it should be considered
a bug. 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. time of a major release, support for that Ruby version may be dropped.
## Copyright ## Copyright
Copyright (c) 2009-2012 [Rick Olson](mailto:technoweenie@gmail.com), zack hobson. Copyright (c) 2009-2012 [Rick Olson](mailto:technoweenie@gmail.com), zack hobson.
See [LICENSE][] for details. 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