Class: Hyperclient::EntryPoint

Inherits:
Link
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/hyperclient/entry_point.rb

Overview

The EntryPoint is the main public API for Hyperclient. It is used to initialize an API client and setup the configuration.

Examples:

client = Hyperclient::EntryPoint.new('http://my.api.org')

client = Hyperclient::EntryPoint.new('http://my.api.org') do |entry_point|
  entry_point.connection do |conn|
    conn.use Faraday::Request::OAuth
  end
  entry_point.headers['Access-Token'] = 'token'
end

Instance Method Summary collapse

Methods inherited from Link

#_delete, #_deprecation, #_expand, #_get, #_head, #_hreflang, #_name, #_options, #_patch, #_post, #_profile, #_put, #_resource, #_templated?, #_title, #_type, #_uri_template, #_url, #_variables, #delegate_method, #http_method, #inspect, #method_missing, #respond_to_missing?, #to_ary, #to_s

Constructor Details

#initialize(url) {|_self| ... } ⇒ EntryPoint

Initializes an EntryPoint.

Parameters:

  • url —

    A String with the entry point of your API.

Yields:

  • (_self)

Yield Parameters:



39
40
41
42
43
 
# File 'lib/hyperclient/entry_point.rb', line 39

def initialize(url, &_block)
  @link = { 'href' => url }
  @entry_point = self
  yield self if block_given?
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Hyperclient::Link

Instance Method Details

#connection(options = {}, &block) ⇒ Object

A Faraday connection to use as a HTTP client.

Parameters:

  • options (defaults to: {}) —

    A Hash containing additional options to pass to Farday. Use

  • if (default: false) —

    you want to skip using default Faraday options set by

  • Hyperclient.

Returns:

  • a Faraday::Connection.



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/hyperclient/entry_point.rb', line 52

def connection(options = {}, &block)
  @faraday_options ||= options.dup
  if block_given?
    fail ConnectionAlreadyInitializedError if @connection
    if @faraday_options.delete(:default) == false
      @faraday_block = block
    else
      @faraday_block = lambda do |conn|
        default_faraday_block.call conn
        block.call conn
      end
    end
  else
    @connection ||= Faraday.new(_url, faraday_options, &faraday_block)
  end
end

#default_faraday_block ⇒ Object (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a block to initialize the Faraday connection. The default block includes a middleware to encode requests as JSON, a response middleware to parse JSON responses and sets the adapter as NetHttp.

These middleware can always be changed by accessing the Faraday connection.

Returns:

  • a block.



126
127
128
129
130
131
132
133
134
 
# File 'lib/hyperclient/entry_point.rb', line 126

def default_faraday_block
  lambda do |connection|
    connection.use Faraday::Response::RaiseError
    connection.use FaradayMiddleware::FollowRedirects
    connection.request :hal_json
    connection.response :hal_json, content_type: /\bjson$/
    connection.adapter :net_http
  end
end

#default_headers ⇒ Object (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the default headers to initialize the Faraday connection. The default headers et the Content-Type and Accept to application/json.

Returns:

  • a Hash.



140
141
142
 
# File 'lib/hyperclient/entry_point.rb', line 140

def default_headers
  { 'Content-Type' => 'application/hal+json', 'Accept' => 'application/hal+json,application/json' }
end

#faraday_block ⇒ Object

Faraday block used with every API request.

Returns:

  • a Proc.



103
104
105
 
# File 'lib/hyperclient/entry_point.rb', line 103

def faraday_block
  @faraday_block ||= default_faraday_block
end

#faraday_block=(value) ⇒ Object

Set a Faraday block to use with every API request.

Parameters:

  • value —

    A Proc accepting a Faraday::Connection.



110
111
112
113
 
# File 'lib/hyperclient/entry_point.rb', line 110

def faraday_block=(value)
  fail ConnectionAlreadyInitializedError if @connection
  @faraday_block = value
end

#faraday_options ⇒ Object

Options passed to Faraday

Returns:

  • a Hash.



88
89
90
 
# File 'lib/hyperclient/entry_point.rb', line 88

def faraday_options
  (@faraday_options ||= {}).merge(headers: headers)
end

#faraday_options=(value) ⇒ Object

Set Faraday connection options.

Parameters:

  • value —

    A Hash containing options to pass to Faraday



95
96
97
98
 
# File 'lib/hyperclient/entry_point.rb', line 95

def faraday_options=(value)
  fail ConnectionAlreadyInitializedError if @connection
  @faraday_options = value
end

#headers ⇒ Object

Headers included with every API request.

Returns:

  • a Hash.



72
73
74
75
 
# File 'lib/hyperclient/entry_point.rb', line 72

def headers
  return @connection.headers if @connection
  @headers ||= default_headers
end

#headers=(value) ⇒ Object

Set headers.

Parameters:

  • value —

    A Hash containing headers to include with every API request.



80
81
82
83
 
# File 'lib/hyperclient/entry_point.rb', line 80

def headers=(value)
  fail ConnectionAlreadyInitializedError if @connection
  @headers = value
end