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
@private
@private
Public Class Methods
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
@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/castle-her/api.rb, line 28 def initialize(*args, &blk) setup(*args, &blk) end
Setup a default API
connection. Accepted arguments and options are the same as {API#setup}.
# File lib/castle-her/api.rb, line 12 def self.setup(opts={}, &block) @default_api = new(opts, &block) end
Private Class Methods
@private
# File lib/castle-her/api.rb, line 109 def self.default_api(opts={}) defined?(@default_api) ? @default_api : nil end
Public Instance Methods
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/castle-her/api.rb, line 87 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 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/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