mirror of
https://github.com/lostisland/faraday.git
synced 2025-10-05 00:05:35 -04:00
improve Readme
This commit is contained in:
Mislav Marohnić
parent
ac1b537f49
commit
ffa01e253a
121
README.md
121
README.md
@ -6,11 +6,11 @@ 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.
|
||||
@ -18,15 +18,10 @@ 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 ##
|
||||
@ -34,7 +29,7 @@ end
|
||||
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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user