Permalink
Browse files

Release 0.8.0

  • Loading branch information...
1 parent e09cf33 commit 416016f31e55673fe85871dbb9a39a9ed8638879 @technoweenie committed Apr 23, 2012
Showing with 57 additions and 21 deletions.
  1. +44 −17 README.md
  2. +12 −3 faraday.gemspec
  3. +1 −1 lib/faraday.rb
View
@@ -1,9 +1,22 @@
-# faraday [![Build Status](https://secure.travis-ci.org/technoweenie/faraday.png?branch=master)][travis] [![Dependency Status](https://gemnasium.com/technoweenie/faraday.png?travis)][gemnasium]
-Modular HTTP client library that uses middleware. Heavily inspired by Rack.
-
+# Faraday [![Build Status](https://secure.travis-ci.org/technoweenie/faraday.png?branch=master)][travis] [![Dependency Status](https://gemnasium.com/technoweenie/faraday.png?travis)][gemnasium]
[travis]: http://travis-ci.org/technoweenie/faraday
[gemnasium]: https://gemnasium.com/technoweenie/faraday
+Faraday is an HTTP client lib that provides a common interface over many
+adapters (such as Net::HTTP) and embraces the concept of Rack middleware when
+processing the request/response cycle.
+
+Faraday supports these adapters:
+
+* 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.
+
## <a name="usage"></a>Usage
```ruby
@@ -23,7 +36,7 @@ end
response = conn.get '/nigiri/sake.json' # GET http://sushi.com/nigiri/sake.json
response.body
-conn.get '/nigiri', 'X-Awesome' => true # custom request header
+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
@@ -65,24 +78,30 @@ 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.
+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.
```ruby
conn = Faraday.new(:url => 'http://sushi.com') do |builder|
# POST/PUT params encoders:
- builder.request :multipart
- builder.request :url_encoded
+ builder.request :multipart
+ builder.request :url_encoded
- builder.adapter :net_http
+ builder.adapter :net_http
end
```
This request middleware setup affects POST/PUT requests in the following way:
-1. `Request::Multipart` checks for files in the payload, otherwise leaves everything untouched;
-2. `Request::UrlEncoded` encodes as "application/x-www-form-urlencoded" if not already encoded or of another type
+1. `Request::Multipart` checks for files in the payload, otherwise leaves
+ everything untouched;
+2. `Request::UrlEncoded` encodes as "application/x-www-form-urlencoded" if not
+ already encoded or of another type
-Swapping middleware means giving the other priority. Specifying the "Content-Type" for the request is explicitly stating which middleware should process it.
+Swapping middleware means giving the other priority. Specifying the
+"Content-Type" for the request is explicitly stating which middleware should
+process it.
Examples:
@@ -97,7 +116,8 @@ conn.put '/profile', payload
```
## Writing middleware
-Middleware are classes that respond to `call()`. They wrap the request/response cycle.
+Middleware are classes that respond to `call()`. They wrap the request/response
+cycle.
```ruby
def call(env)
@@ -109,9 +129,12 @@ def call(env)
end
```
-It's important to do all processing of the response only in the `on_complete` block. This enables middleware to work in parallel mode where requests are asynchronous.
+It's important to do all processing of the response only in the `on_complete`
+block. This enables middleware to work in parallel mode where requests are
+asynchronous.
-The `env` is a hash with symbol keys that contains info about the request and, later, response. Some keys are:
+The `env` is a hash with symbol keys that contains info about the request and,
+later, response. Some keys are:
```
# request phase
@@ -164,7 +187,6 @@ stubs.verify_stubbed_calls
## <a name="todo"></a>TODO
* support streaming requests/responses
* better stubbing API
-* Add curb, em-http, fast_http
## <a name="pulls"></a>Note on Patches/Pull Requests
1. Fork the project.
@@ -174,7 +196,11 @@ stubs.verify_stubbed_calls
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 me a pull request. Bonus points for topic branches.
+5. Send us a pull request. Bonus points for topic branches.
+
+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).
## <a name="versions"></a>Supported Ruby Versions
This library aims to support and is [tested against][travis] the following Ruby
@@ -204,6 +230,7 @@ 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.
## <a name="copyright"></a>Copyright
-Copyright (c) 2009 [Rick Olson](mailto:technoweenie@gmail.com), zack hobson. See [LICENSE][] for details.
+Copyright (c) 2009-12 [Rick Olson](mailto:technoweenie@gmail.com), zack hobson.
+See [LICENSE][] for details.
[license]: https://github.com/technoweenie/faraday/blob/master/LICENSE.md
View
@@ -3,7 +3,7 @@ Gem::Specification.new do |s|
s.required_rubygems_version = Gem::Requirement.new(">= 1.3.5") if s.respond_to? :required_rubygems_version=
s.name = 'faraday'
- s.version = '0.8.0.rc2'
+ s.version = '0.8.0'
s.summary = "HTTP/REST API client library."
# TODO: s.description
@@ -28,20 +28,22 @@ Gem::Specification.new do |s|
faraday.gemspec
lib/faraday.rb
lib/faraday/adapter.rb
- lib/faraday/adapter/action_dispatch.rb
lib/faraday/adapter/em_http.rb
lib/faraday/adapter/em_synchrony.rb
lib/faraday/adapter/em_synchrony/parallel_manager.rb
lib/faraday/adapter/excon.rb
lib/faraday/adapter/net_http.rb
+ lib/faraday/adapter/net_http_persistent.rb
lib/faraday/adapter/patron.rb
+ lib/faraday/adapter/rack.rb
lib/faraday/adapter/test.rb
lib/faraday/adapter/typhoeus.rb
lib/faraday/builder.rb
lib/faraday/connection.rb
lib/faraday/error.rb
lib/faraday/middleware.rb
lib/faraday/request.rb
+ lib/faraday/request/authorization.rb
lib/faraday/request/basic_authentication.rb
lib/faraday/request/multipart.rb
lib/faraday/request/retry.rb
@@ -52,9 +54,16 @@ Gem::Specification.new do |s|
lib/faraday/response/raise_error.rb
lib/faraday/upload_io.rb
lib/faraday/utils.rb
- test/adapters/live_test.rb
+ test/adapters/default_test.rb
+ test/adapters/em_http_test.rb
+ test/adapters/em_synchrony_test.rb
+ test/adapters/excon_test.rb
+ test/adapters/integration.rb
test/adapters/logger_test.rb
+ test/adapters/net_http_persistent_test.rb
test/adapters/net_http_test.rb
+ test/adapters/patron_test.rb
+ test/adapters/rack_test.rb
test/adapters/test_middleware_test.rb
test/adapters/typhoeus_test.rb
test/authentication_middleware_test.rb
View
@@ -1,5 +1,5 @@
module Faraday
- VERSION = "0.8.0.rc2"
+ VERSION = "0.8.0"
class << self
attr_accessor :root_path, :lib_path

0 comments on commit 416016f

Please sign in to comment.