Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Replace “builder” with “connection” in docs and code

  • Loading branch information...
commit 1afdd8229c4c96b2b70c609c2f536feca2193bea 1 parent 7818032
@remiprev authored
View
84 README.md
@@ -22,10 +22,10 @@ First, you have to define which API your models will be bound to. For example, w
```ruby
# config/initializers/her.rb
-Her::API.setup :url => "https://api.example.com" do |builder|
- builder.use Faraday::Request::UrlEncoded
- builder.use Her::Middleware::DefaultParseJSON
- builder.use Faraday::Adapter::NetHttp
+Her::API.setup :url => "https://api.example.com" do |connection|
+ connection.use Faraday::Request::UrlEncoded
+ connection.use Her::Middleware::DefaultParseJSON
+ connection.use Faraday::Adapter::NetHttp
end
```
@@ -64,11 +64,11 @@ You can look into the `examples` directory for sample applications using Her.
## Middleware
-Since Her relies on [Faraday](https://github.com/technoweenie/faraday) to send HTTP requests, you can add additional middleware to handle requests and responses. Using the block in the `setup` call, you have access to Faraday’s `builder` object and are able to customize the middleware stack used on each request and response.
+Since Her relies on [Faraday](https://github.com/technoweenie/faraday) to send HTTP requests, you can add additional middleware to handle requests and responses. Using the block in the `setup` call, you have access to Faraday’s `connection` object and are able to customize the middleware stack used on each request and response.
### Authentication
-Her doesn’t support any kind of authentication. However, it’s very easy to implement one with a request middleware. Using the builder block, we add it to the default list of middleware.
+Her doesn’t support any kind of authentication. However, it’s very easy to implement one with a request middleware. Using the connection block, we add it to the default list of middleware.
```ruby
class MyAuthentication < Faraday::Middleware
@@ -82,13 +82,13 @@ class MyAuthentication < Faraday::Middleware
end
end
-Her::API.setup :url => "https://api.example.com" do |builder|
+Her::API.setup :url => "https://api.example.com" do |connection|
# This token could be stored in the client session
- builder.use MyAuthentication, :token => "bb2b2dd75413d32c1ac421d39e95b978d1819ff611f68fc2fdd5c8b9c7331192"
+ connection.use MyAuthentication, :token => "bb2b2dd75413d32c1ac421d39e95b978d1819ff611f68fc2fdd5c8b9c7331192"
- builder.use Faraday::Request::UrlEncoded
- builder.use Her::Middleware::DefaultParseJSON
- builder.use Faraday::Adapter::NetHttp
+ connection.use Faraday::Request::UrlEncoded
+ connection.use Her::Middleware::DefaultParseJSON
+ connection.use Faraday::Adapter::NetHttp
end
```
@@ -106,7 +106,7 @@ By default, Her handles JSON data. It expects the resource/collection data to be
[{ "id" : 1, "name" : "Tobias Fünke" }]
```
-However, you can define your own parsing method, using a response middleware. The middleware is expected to set `env[:body]` to a hash with three keys: `data`, `errors` and `metadata`. The following code enables parsing JSON data and treating the result as first-level properties. Using the builder block, we then replace the default parser with our custom parser.
+However, you can define your own parsing method, using a response middleware. The middleware is expected to set `env[:body]` to a hash with three keys: `data`, `errors` and `metadata`. The following code enables parsing JSON data and treating the result as first-level properties. Using the connection block, we then replace the default parser with our custom parser.
```ruby
class MyCustomParser < Faraday::Response::Middleware
@@ -120,10 +120,10 @@ class MyCustomParser < Faraday::Response::Middleware
end
end
-Her::API.setup :url => "https://api.example.com" do |builder|
- builder.use Faraday::Request::UrlEncoded
- builder.use MyCustomParser
- builder.use Faraday::Adapter::NetHttp
+Her::API.setup :url => "https://api.example.com" do |connection|
+ connection.use Faraday::Request::UrlEncoded
+ connection.use MyCustomParser
+ connection.use Faraday::Adapter::NetHttp
end
# User.find(1) will now expect "https://api.example.com/users/1" to return something like '{ "result" => { "id": 1, "name": "Tobias Fünke" }, "errors" => [] }'
```
@@ -151,11 +151,11 @@ TWITTER_CREDENTIALS = {
:token_secret => ""
}
-Her::API.setup :url => "https://api.twitter.com/1/" do |builder|
- builder.use FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
- builder.use Faraday::Request::UrlEncoded
- builder.use Her::Middleware::DefaultParseJSON
- builder.use Faraday::Adapter::NetHttp
+Her::API.setup :url => "https://api.twitter.com/1/" do |connection|
+ connection.use FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
+ connection.use Faraday::Request::UrlEncoded
+ connection.use Her::Middleware::DefaultParseJSON
+ connection.use Faraday::Adapter::NetHttp
end
class Tweet
@@ -199,11 +199,11 @@ end
# We should be probably using something like Memcached here, not a global object
$cache = MyCache.new
-Her::API.setup :url => "https://api.example.com" do |builder|
- builder.use Faraday::Request::UrlEncoded
- builder.use FaradayMiddleware::Caching, $cache
- builder.use Her::Middleware::DefaultParseJSON
- builder.use Faraday::Adapter::NetHttp
+Her::API.setup :url => "https://api.example.com" do |connection|
+ connection.use Faraday::Request::UrlEncoded
+ connection.use FaradayMiddleware::Caching, $cache
+ connection.use Her::Middleware::DefaultParseJSON
+ connection.use Faraday::Adapter::NetHttp
end
class User
@@ -403,17 +403,17 @@ It is possible to use different APIs for different models. Instead of calling `H
```ruby
# config/initializers/her.rb
$my_api = Her::API.new
-$my_api.setup :url => "https://my_api.example.com" do |builder|
- builder.use Faraday::Request::UrlEncoded
- builder.use Her::Middleware::DefaultParseJSON
- builder.use Faraday::Adapter::NetHttp
+$my_api.setup :url => "https://my_api.example.com" do |connection|
+ connection.use Faraday::Request::UrlEncoded
+ connection.use Her::Middleware::DefaultParseJSON
+ connection.use Faraday::Adapter::NetHttp
end
$other_api = Her::API.new
-$other_api.setup :url => "https://other_api.example.com" do |builder|
- builder.use Faraday::Request::UrlEncoded
- builder.use Her::Middleware::DefaultParseJSON
- builder.use Faraday::Adapter::NetHttp
+$other_api.setup :url => "https://other_api.example.com" do |connection|
+ connection.use Faraday::Request::UrlEncoded
+ connection.use Her::Middleware::DefaultParseJSON
+ connection.use Faraday::Adapter::NetHttp
end
```
@@ -443,10 +443,10 @@ When initializing `Her::API`, you can pass any parameter supported by `Faraday.n
```ruby
ssl_options = { :ca_path => "/usr/lib/ssl/certs" }
-Her::API.setup :url => "https://api.example.com", :ssl => ssl_options do |builder|
- builder.use Faraday::Request::UrlEncoded
- builder.use Her::Middleware::DefaultParseJSON
- builder.use Faraday::Adapter::NetHttp
+Her::API.setup :url => "https://api.example.com", :ssl => ssl_options do |connection|
+ connection.use Faraday::Request::UrlEncoded
+ connection.use Her::Middleware::DefaultParseJSON
+ connection.use Faraday::Adapter::NetHttp
end
```
@@ -464,10 +464,10 @@ end
# spec/models/post.rb
describe Post do
before do
- Her::API.setup :url => "http://api.example.com" do |builder|
- builder.use Her::Middleware::FirstLevelParseJSON
- builder.use Faraday::Request::UrlEncoded
- builder.adapter :test do |stub|
+ Her::API.setup :url => "http://api.example.com" do |connection|
+ connection.use Her::Middleware::FirstLevelParseJSON
+ connection.use Faraday::Request::UrlEncoded
+ connection.adapter :test do |stub|
stub.get("/users/popular") { |env| [200, {}, [{ :id => 1, :name => "Tobias Fünke" }, { :id => 2, :name => "Lindsay Fünke" }].to_json] }
end
end
View
14 UPGRADE.md
@@ -4,17 +4,17 @@ Here is a list of backward-incompatible changes that were introduced while Her i
* Her no longer includes default middleware when making HTTP requests. The user has now to define all the needed middleware. Before:
- Her::API.setup :url => "https://api.example.com" do |builder|
- builder.insert(0, FaradayMiddle::OAuth)
+ Her::API.setup :url => "https://api.example.com" do |connection|
+ connection.insert(0, FaradayMiddle::OAuth)
end
Now:
- Her::API.setup :url => "https://api.example.com" do |builder|
- builder.use FaradayMiddle::OAuth
- builder.use Her::Middleware::FirstLevelParseJSON
- builder.use Faraday::Request::UrlEncoded
- builder.use Faraday::Adapter::NetHttp
+ Her::API.setup :url => "https://api.example.com" do |connection|
+ connection.use FaradayMiddle::OAuth
+ connection.use Her::Middleware::FirstLevelParseJSON
+ connection.use Faraday::Request::UrlEncoded
+ connection.use Faraday::Adapter::NetHttp
end
## 0.2
View
46 examples/twitter-oauth/app.rb
@@ -20,11 +20,11 @@ def on_complete(env)
}
# Initialize API
-Her::API.setup :url => "https://api.twitter.com/1/" do |builder|
- builder.use FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
- builder.use Faraday::Request::UrlEncoded
- builder.use TwitterParser
- builder.use Faraday::Adapter::NetHttp
+Her::API.setup :url => "https://api.twitter.com/1/" do |connection|
+ connection.use FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
+ connection.use Faraday::Request::UrlEncoded
+ connection.use TwitterParser
+ connection.use Faraday::Adapter::NetHttp
end
# Define classes
@@ -48,3 +48,39 @@ def username
@tweets = Tweet.mentions
haml :index
end
+
+############################################
+
+# config/initializers/her.rb
+Her::API.setup :url => "https://api.example.com" do |connection|
+ connection.use MyAuthentication
+ connection.use Faraday::Request::UrlEncoded
+ connection.use Her::Middleware::DefaultParseJSON
+ connection.use Faraday::Adapter::NetHttp
+end
+
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+ before_filter do
+ MyApp.current_user = session[:user_id] ? User.find(session[:user_id]) : nil
+ end
+end
+
+# lib/my_app.rb
+class MyApp
+ def self.current_user=(user)
+ @current_user = user
+ end
+
+ def self.current_user
+ @current_user
+ end
+end
+
+# lib/my_authentication.rb
+class MyAuthentication < Faraday::Middleware
+ def call(env)
+ env[:request_headers]["X-API-Token"] = MyApp.current_user.token if MyApp.current_user?
+ @app.call(env)
+ end
+end
View
10 examples/twitter-search/app.rb
@@ -33,11 +33,11 @@ def fetch(key)
$cache = MyCache.new
# Initialize API
-Her::API.setup :url => "http://search.twitter.com" do |builder|
- builder.use Faraday::Request::UrlEncoded
- builder.use FaradayMiddleware::Caching, $cache
- builder.use TwitterSearchParser
- builder.use Faraday::Adapter::NetHttp
+Her::API.setup :url => "http://search.twitter.com" do |connection|
+ connection.use Faraday::Request::UrlEncoded
+ connection.use FaradayMiddleware::Caching, $cache
+ connection.use TwitterSearchParser
+ connection.use Faraday::Adapter::NetHttp
end
# Define classes
View
16 lib/her/api.rb
@@ -29,10 +29,10 @@ def self.setup(attrs={}, &block) # {{{
# @all.call(env)
# end
# end
- # Her::API.setup :url => "https://api.example.com" do |builder|
- # builder.use Faraday::Request::UrlEncoded
- # builder.use Her::Middleware::DefaultParseJSON
- # builder.use Faraday::Adapter::NetHttp
+ # Her::API.setup :url => "https://api.example.com" do |connection|
+ # connection.use Faraday::Request::UrlEncoded
+ # connection.use Her::Middleware::DefaultParseJSON
+ # connection.use Faraday::Adapter::NetHttp
# end
#
# @example A custom parse middleware
@@ -44,10 +44,10 @@ def self.setup(attrs={}, &block) # {{{
# env[:body] = { :data => json, :errors => errors, :metadata => metadata }
# end
# end
- # Her::API.setup :url => "https://api.example.com" do |builder|
- # builder.use Faraday::Request::UrlEncoded
- # builder.use MyCustomParser
- # builder.use Faraday::Adapter::NetHttp
+ # Her::API.setup :url => "https://api.example.com" do |connection|
+ # connection.use Faraday::Request::UrlEncoded
+ # connection.use MyCustomParser
+ # connection.use Faraday::Adapter::NetHttp
# end
def setup(attrs={}) # {{{
attrs[:url] = attrs.delete(:base_uri) if attrs.include?(:base_uri) # Support legacy :base_uri option
Please sign in to comment.
Something went wrong with that request. Please try again.