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 Attribute Summary collapse

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:



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

def initialize(url, &_block)
  @link = { 'href' => url }
  @entry_point = self
  @options = { async: true }
  @connection = nil
  @resource = nil
  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 Attribute Details

#options ⇒ Object

Read/Set options.

Parameters:

  • value —

    A Hash containing the client options. Use { async: false } to

  • to —

    disable the default behavior of performing requests asynchronously

  • using —

    futures.



122
123
124
 
# File 'lib/hyperclient/entry_point.rb', line 122

def options
  @options
end

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.



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

def connection(options = {}, &block)
  @faraday_options ||= options.dup
  if block_given?
    raise ConnectionAlreadyInitializedError if @connection
    @faraday_block = if @faraday_options.delete(:default) == false
                       block
                     else
                       lambda do |conn|
                         default_faraday_block.call conn
                         yield 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.



135
136
137
138
139
140
141
142
143
144
 
# File 'lib/hyperclient/entry_point.rb', line 135

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
    connection.options.params_encoder = Faraday::FlatParamsEncoder
  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.



150
151
152
 
# File 'lib/hyperclient/entry_point.rb', line 150

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.



105
106
107
 
# File 'lib/hyperclient/entry_point.rb', line 105

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.

Raises:



112
113
114
115
 
# File 'lib/hyperclient/entry_point.rb', line 112

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

#faraday_options ⇒ Object

Options passed to Faraday

Returns:

  • a Hash.



90
91
92
 
# File 'lib/hyperclient/entry_point.rb', line 90

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

Raises:



97
98
99
100
 
# File 'lib/hyperclient/entry_point.rb', line 97

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

#headers ⇒ Object

Headers included with every API request.

Returns:

  • a Hash.



74
75
76
77
 
# File 'lib/hyperclient/entry_point.rb', line 74

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.

Raises:



82
83
84
85
 
# File 'lib/hyperclient/entry_point.rb', line 82

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