Class: McCracken::Connection

Inherits:
Object
  • Object
show all
Defined in:
lib/mccracken/connection.rb

Overview

Faraday::Connection wrapper for making JSON API Requests

Constant Summary collapse

CONNECTION_OPTIONS = 
[:response_key_format].freeze
FARADAY_OPTIONS = 
[:request, :proxy, :ssl, :builder, :url,
:parallel_manager, :params, :headers, :builder_class].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args, &block) ⇒ Connection

Create a new connection. A connection serves as a thin wrapper around a a faraday connection that includes two pieces of middleware for handling JSON API Spec

Examples:

Setting the key format

$my_connection = McCracken::Connection.new response_key_format: :dasherize, url: "http://api.example.com" do |c|
  c.use Your::Custom::Middleware
end

$my_connection = McCracken::Connection.new response_key_format: :camelize, url: "http://api.example.com" do |c|
  c.use Your::Custom::Middleware
end

Creating a new connection

$my_connection = McCracken::Connection.new url: "http://api.example.com" do |c|
  c.use Your::Custom::Middleware
end

class User < McCracken::Resource
  self.type = :users
  mccracken.connection = $my_connection
end

Parameters:

See Also:



40
41
42
 
# File 'lib/mccracken/connection.rb', line 40

def initialize(args, &block)
  configure(args, &block)
end

Instance Attribute Details

#faraday ⇒ Object (readonly) 



6
7
8
 
# File 'lib/mccracken/connection.rb', line 6

def faraday
  @faraday
end

#options ⇒ Object (readonly) 



6
7
8
 
# File 'lib/mccracken/connection.rb', line 6

def options
  @options
end

Instance Method Details

#clone ⇒ Object

Clones a connection



45
46
47
 
# File 'lib/mccracken/connection.rb', line 45

def clone
  Connection.new(options.dup, &@block)
end

#configure(args = {}, &block) ⇒ Object

Configure the connection

Examples:

Setting up the default API connection

McCracken::Connection.new url: "http://api.example.com"

A custom middleware added to the default list

class MyTokenAuth < Faraday::Middleware
  def call(env)
    env[:request_headers]["X-API-Token"] = "SECURE_TOKEN"
    @app.call(env)
  end
end

McCracken::Connection.new url: "http://api.example.com" do |c|
  c.use MyTokenAuth
end

Use a custom adapter

McCracken::Connection.new adapter: [:rack, MyRackApp.new]

Parameters:

Returns:

  • Faraday::Connection



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/mccracken/connection.rb', line 102

def configure(args={}, &block)
  # Cache these for #clone method
  @options = args
  @block = block

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

    conn.request :"McCracken::Middleware::EncodeJsonApi", key_formatter
    conn.response :"McCracken::Middleware::JsonParser", key_formatter

    conn.adapter(*@options.fetch(:adapter, Faraday.default_adapter))
  end
end

#get(path: nil, params: nil, headers: nil) ⇒ Faraday::Response

JSON API Spec GET request

Examples:

making a GET request

@connection.get(path: 'addresses', params: {include: 'user'}, headers: {'X-API-Token' => '2kewl'})

Parameters:

  • [Hash,nil] (Hash) —

    a customizable set of options

  • [String] (Hash) —

    a customizable set of options

  • [Hash] (Hash) —

    a customizable set of options

Returns:

  • (Faraday::Response) 


58
59
60
61
62
63
 
# File 'lib/mccracken/connection.rb', line 58

def get(path: nil, params: nil, headers: nil)
  faraday.get do |request|
    request.headers.merge!(headers) if headers
    request.url path.to_s, externalize_keys(params)
  end
end

#post(body: {}, path: nil, headers: nil, http_method: :post) ⇒ Faraday::Response

JSON API Spec POST request

Parameters:

  • [Hash,nil] (Hash) —

    a customizable set of options

  • [String] (Hash) —

    a customizable set of options

  • [Hash] (Hash) —

    a customizable set of options

  • [Type] (Hash) —

    a customizable set of options

Returns:

  • (Faraday::Response) 


72
73
74
75
76
77
78
 
# File 'lib/mccracken/connection.rb', line 72

def post(body: {}, path: nil, headers: nil, http_method: :post)
  faraday.send(http_method) do |request|
    request.headers.merge!(headers) if headers
    request.url path.to_s
    request.body = body
  end
end

#response_key_format ⇒ Object 



133
134
135
 
# File 'lib/mccracken/connection.rb', line 133

def response_key_format
  @options[:response_key_format]
end

#url ⇒ Object 



129
130
131
 
# File 'lib/mccracken/connection.rb', line 129

def url
  faraday.url_prefix.to_s
end