Class: Her::API

Inherits:
Object
  • Object
show all
Defined in:
lib/castle-her/api.rb

Overview

This class is where all HTTP requests are made. Before using Her, you must configure it so it knows where to make those requests. In Rails, this is usually done in ‘config/initializers/her.rb`:

Constant Summary collapse

FARADAY_OPTIONS =

Constants

[:request, :proxy, :ssl, :builder, :url, :parallel_manager, :params, :headers, :builder_class].freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args, &blk) ⇒ API

Create a new API object. This is useful to create multiple APIs and use them with the ‘uses_api` method. If your application uses only one API, you should use Her::API.setup to configure the default API

Examples:

Setting up a new API

api = Her::API.new :url => "https://api.example" do |connection|
  connection.use Faraday::Request::UrlEncoded
  connection.use Her::Middleware::DefaultParseJSON
end

class User
  uses_api api
end



28
29
30
 
# File 'lib/castle-her/api.rb', line 28

def initialize(*args, &blk)
  setup(*args, &blk)
end

Class Method Details

.setup(opts = {}, &block) ⇒ Object

Setup a default API connection. Accepted arguments and options are the same as #setup.



12
13
14
 
# File 'lib/castle-her/api.rb', line 12

def self.setup(opts={}, &block)
  @default_api = new(opts, &block)
end

Instance Method Details

#setup(opts = {}, &blk) ⇒ Object

Setup the API connection.

Examples:

Setting up the default API connection

Her::API.setup :url => "https://api.example"

A custom middleware added to the default list

class MyAuthentication < Faraday::Middleware
  def call(env)
    env[:request_headers]["X-API-Token"] = "bb2b2dd75413d32c1ac421d39e95b978d1819ff611f68fc2fdd5c8b9c7331192"
    @app.call(env)
  end
end
Her::API.setup :url => "https://api.example.com" do |connection|
  connection.use Faraday::Request::UrlEncoded
  connection.use Her::Middleware::DefaultParseJSON
  connection.use MyAuthentication
  connection.use Faraday::Adapter::NetHttp
end

A custom parse middleware

class MyCustomParser < Faraday::Response::Middleware
  def on_complete(env)
    json = JSON.parse(env[:body], :symbolize_names => true)
    errors = json.delete(:errors) || {}
    metadata = json.delete(:metadata) || []
    env[:body] = { :data => json, :errors => errors, :metadata => metadata }
  end
end
Her::API.setup :url => "https://api.example.com" do |connection|
  connection.use Faraday::Request::UrlEncoded
  connection.use MyCustomParser
  connection.use Faraday::Adapter::NetHttp
end

Parameters:

  • opts (Hash) (defaults to: {}) —

    the Faraday options

Options Hash (opts):

Returns:

  • Faraday::Connection



71
72
73
74
75
76
77
78
79
80
 
# File 'lib/castle-her/api.rb', line 71

def setup(opts={}, &blk)
  opts[:url] = opts.delete(:base_uri) if opts.include?(:base_uri) # Support legacy :base_uri option
  @options = opts

  faraday_options = @options.reject { |key, value| !FARADAY_OPTIONS.include?(key.to_sym) }
  @connection = Faraday.new(faraday_options) do |connection|
    yield connection if block_given?
  end
  self
end