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, #each, #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:



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

def initialize(url, &_block)
  @link = { 'href' => url }
  @entry_point = self
  @options = {}
  @connection = nil
  @resource = nil
  @key = nil
  @uri_variables = 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.



125
126
127
 
# File 'lib/hyperclient/entry_point.rb', line 125

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.



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

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, &block)
                       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.



138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/hyperclient/entry_point.rb', line 138

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

    block&.call(connection)

    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.



156
157
158
 
# File 'lib/hyperclient/entry_point.rb', line 156

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.



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

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:



116
117
118
119
120
 
# File 'lib/hyperclient/entry_point.rb', line 116

def faraday_block=(value)
  raise ConnectionAlreadyInitializedError if @connection

  @faraday_block = value
end

#faraday_options ⇒ Object

Options passed to Faraday

Returns:

  • a Hash.



93
94
95
 
# File 'lib/hyperclient/entry_point.rb', line 93

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:



100
101
102
103
104
 
# File 'lib/hyperclient/entry_point.rb', line 100

def faraday_options=(value)
  raise ConnectionAlreadyInitializedError if @connection

  @faraday_options = value
end

#headers ⇒ Object

Headers included with every API request.

Returns:

  • a Hash.



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

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:



84
85
86
87
88
 
# File 'lib/hyperclient/entry_point.rb', line 84

def headers=(value)
  raise ConnectionAlreadyInitializedError if @connection

  @headers = value
end