class Her::API

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`:

Constants

FARADAY_OPTIONS

Constants

Attributes

base_uri[R]

@private

connection[R]

@private

options[R]

@private

Public Class Methods

new(*args, &blk) click to toggle source

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 ::setup to configure the default API

@example 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
# File lib/her/api.rb, line 28
def initialize(*args, &blk)
  setup(*args, &blk)
end
setup(opts={}, &block) click to toggle source

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

# File lib/her/api.rb, line 12
def self.setup(opts={}, &block)
  @default_api = new(opts, &block)
end

Private Class Methods

default_api(opts={}) click to toggle source

@private

# File lib/her/api.rb, line 110
def self.default_api(opts={})
  defined?(@default_api) ? @default_api : nil
end

Public Instance Methods

request(opts={}) click to toggle source

Define a custom parsing procedure. The procedure is passed the response object and is expected to return a hash with three keys: a main data Hash, an errors Hash and a metadata Hash.

@private

# File lib/her/api.rb, line 88
def request(opts={})
  method = opts.delete(:_method)
  path = opts.delete(:_path)
  headers = opts.delete(:_headers)
  opts.delete_if { |key, value| key.to_s =~ /^_/ } # Remove all internal parameters
  response = @connection.send method do |request|
    request.headers.merge!(headers) if headers
    if method == :get
      # For GET requests, treat additional parameters as querystring data
      request.url path, opts
    else
      # For POST, PUT and DELETE requests, treat additional parameters as request body
      request.url path
      request.body = opts
    end
  end

  { :parsed_data => response.env[:body], :response => response }
end
setup(opts={}) { |connection| ... } click to toggle source

Setup the API connection.

@param [Hash] opts the Faraday options @option opts [String] :url The main HTTP API root (eg. `api.example.com`) @option opts [String] :ssl A hash containing [SSL options](github.com/lostisland/faraday/wiki/Setting-up-SSL-certificates)

@return Faraday::Connection

@example Setting up the default API connection

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

@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

@example 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
# File lib/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
  @base_uri = opts[:url]
  @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