Class: ApiNavigator::EntryPoint

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

Overview

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

Examples:

client = ApiNavigator::EntryPoint.new('http://my.api.org')
client = ApiNavigator::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, #http_method, #inspect, #method_missing, #respond_to_missing?, #to_ary, #to_s

Constructor Details

#initialize(url, client_identifier = nil) {|_self| ... } ⇒ EntryPoint

Initializes an EntryPoint.

Parameters:

  • url —

    A String with the entry point of your API.

Yields:

  • (_self)

Yield Parameters:



40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/api_navigator/entry_point.rb', line 40

def initialize(url, client_identifier=nil, &_block)
  @link = { 'href' => url }
  @entry_point = self
  @options = {}
  @connection = nil
  @resource = nil
  @key = nil
  @uri_variables = nil
  @client_identifier = client_identifier
  yield self if block_given?
end

Dynamic Method Handling

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

Instance Attribute Details

#client_identifier ⇒ Object (readonly) 



32
33
34
 
# File 'lib/api_navigator/entry_point.rb', line 32

def client_identifier
  @client_identifier
end

#options ⇒ Object

Read/Set options.

Parameters:

  • value —

    A Hash containing the client options.



125
126
127
 
# File 'lib/api_navigator/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

  • ApiNavigator.

Returns:

  • a Faraday::Connection.



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/api_navigator/entry_point.rb', line 59

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.



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

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.



153
154
155
 
# File 'lib/api_navigator/entry_point.rb', line 153

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.



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

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:



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

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

#faraday_options ⇒ Object

Options passed to Faraday

Returns:

  • a Hash.



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

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:



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

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

#headers ⇒ Object

Headers included with every API request.

Returns:

  • a Hash.



79
80
81
82
 
# File 'lib/api_navigator/entry_point.rb', line 79

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:



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

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