Class: Ecoportal::API::Common::Client

Inherits:
Object
  • Object
show all
Includes:
RateThrottling, WithRetry
Defined in:
lib/ecoportal/api/common/client.rb,
lib/ecoportal/api/common/client/error.rb,
lib/ecoportal/api/common/client/time_out.rb,
lib/ecoportal/api/common/client/throughput.rb,
lib/ecoportal/api/common/client/with_retry.rb,
lib/ecoportal/api/common/client/error/checks.rb,
lib/ecoportal/api/common/client/rate_throttling.rb,
lib/ecoportal/api/common/client/throughput/stats.rb,
lib/ecoportal/api/common/client/elastic_apm_integration.rb

Overview

Note:
  • You can see the documentation of the HTTP module in the repository
    • it does extend the module Chainable (chainable.rb),
    • where all the http requests are dev by using HTTP::Client#request (client.rb)
    • which calls build_request (new HTTP::Request) and perform (new HTTP::Connection)
    • to return HTTP::Response (response.rb)

Defined Under Namespace

Modules: ElasticApmIntegration, Error, RateThrottling, TimeOut, WithRetry Classes: Throughput

Constant Summary collapse

DEFAULT_HOST = 
'live.ecoportal.com'.freeze
MAIN_END_POINT = 
'api'.freeze

Constants included from WithRetry

WithRetry::DELAY_REQUEST_RETRY, WithRetry::HANDLED_CONNECTION_ERRORS, WithRetry::RETRY_ATTEMPTS

Constants included from ElasticApmIntegration

ElasticApmIntegration::APM_SERVICE_NAME

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from ElasticApmIntegration

#log_unexpected_server_error

Constructor Details

#initialize(api_key:, version: :unused, host: DEFAULT_HOST, logger: nil, deep_logging: false) ⇒ Client

Note:

the api_key will be automatically added as parameter X-ApiKey in the header of the http requests.

Returns an object that holds the configuration of the api connection.

Parameters:

  • api_key (String) —

    the key version to stablish the api connection.

  • version (String) (defaults to: :unused) —

    it is part of the base url and will determine the api version we query against.

  • host (String) (defaults to: DEFAULT_HOST) —

    api server domain.

  • logger (Logger) (defaults to: nil) —

    an object with Logger interface to generate logs.

  • deep_logging (Boolean) (defaults to: false) —

    whether or not batch responses should be logged



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/ecoportal/api/common/client.rb', line 43

def initialize(api_key:, version: :unused, host: DEFAULT_HOST, logger: nil, deep_logging: false)
  version       = nil     if version == :unused
  @version      = version unless version.nil?
  @api_key      = api_key
  @logger       = logger
  @host         = host
  @deep_logging = deep_logging

  if host.match(/^localhost|^127\.0\.0\.1/)
    @base_uri = "http://#{host}/#{main_end_point}/"
  else
    @base_uri = "https://#{host}/#{main_end_point}/"
  end

  if deep_logging?
    log(:debug) {
      "#{self.version} client initialized pointing at #{host}"
    }
  end

  return unless api_key.nil? || api_key.match(/\A\W*\z/)
  return unless self.version

  log(:error) { 'Api-key missing!' }
end

Instance Attribute Details

#host ⇒ String (readonly)

the remote target server.

Returns:

  • (String) —

    the current value of host



26
27
28
 
# File 'lib/ecoportal/api/common/client.rb', line 26

def host
  @host
end

#logger ⇒ Logger

the logger.

Returns:

  • (Logger) —

    the current value of logger



26
27
28
 
# File 'lib/ecoportal/api/common/client.rb', line 26

def logger
  @logger
end

#version ⇒ Object (readonly)

Returns the value of attribute version.



34
35
36
 
# File 'lib/ecoportal/api/common/client.rb', line 34

def version
  @version
end

Instance Method Details

#base_request ⇒ HTTP

Note:

It configures HTTP so it only allows body data in json format.

Creates a HTTP object adding the X-ApiKey or X-ECOPORTAL-API-KEY param to the header, depending on the API version.

Returns:

  • (HTTP) —

    HTTP object.



151
152
153
154
155
156
157
158
159
 
# File 'lib/ecoportal/api/common/client.rb', line 151

def base_request
  @base_request ||=
    case @version
    when 'v2'
      HTTP.headers('X-ECOPORTAL-API-KEY' => api_key).accept(:json)
    else
      HTTP.headers('X-ApiKey' => api_key).accept(:json)
    end
end

#delete(path) ⇒ Common::Reponse

Sends an http DELETE request against the api version using path to complete the base url.

Parameters:

  • path (String) —

    the tail that completes the url of the request.

Returns:

  • (Common::Reponse) —

    the basic custom response object.



122
123
124
125
126
127
128
 
# File 'lib/ecoportal/api/common/client.rb', line 122

def delete(path)
  instrument('DELETE', path) do
    request do |http|
      http.delete(url_for(path))
    end
  end
end

#get(path, params: {}) ⇒ Common::Reponse

Sends an http GET request against the api version using path to complete the base url, and adding the key_value pairs of params in the http header.

Parameters:

  • path (String) —

    the tail that completes the url of the request.

  • params (Hash) (defaults to: {}) —

    the header paramters of the http request (not including the api key).

Options Hash (params:):

  • :page (String) —

    the current page we are requesting with given the :per_page offset.

  • :per_page (String) —

    the offset or the number of entries you get per request.

  • :q (String) —

    some text to search. Omit this parameter to target all the entries.

Returns:

  • (Common::Reponse) —

    the basic custom response object.



77
78
79
80
81
82
83
 
# File 'lib/ecoportal/api/common/client.rb', line 77

def get(path, params: {})
  instrument('GET', path, params) do
    request do |http|
      http.get(url_for(path), params: params)
    end
  end
end

#patch(path, data:) ⇒ Common::Reponse

Note:

it automatically adds the http header param Content-Type as application/json

Sends an http PATCH request against the api version using path to complete the base url, and the data as a body of the http request.

Parameters:

  • path (String) —

    the tail that completes the url of the request.

  • data (String) —

    the body of the query in json format.

Returns:

  • (Common::Reponse) —

    the basic custom response object.



111
112
113
114
115
116
117
 
# File 'lib/ecoportal/api/common/client.rb', line 111

def patch(path, data:)
  instrument('PATCH', path, data) do
    request do |http|
      http.patch(url_for(path), json: data)
    end
  end
end

#post(path, data:, params: {}) ⇒ Common::Reponse

Note:

it automatically adds the http header param Content-Type as application/json

Sends an http POST request against the api version using path to complete the base url, and the data as a body of the http request.

Parameters:

  • path (String) —

    the tail that completes the url of the request.

  • data (String) —

    the body of the query in json format.

  • params (Hash) (defaults to: {}) —

    the header paramters of the http request (not including the api key).

Options Hash (params:):

  • URL (String) —

    params; will depend on he API being used.

Returns:

  • (Common::Reponse) —

    the basic custom response object.



93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/ecoportal/api/common/client.rb', line 93

def post(path, data:, params: {})
  instrument('POST', path, params) do
    request do |http|
      http.post(
        url_for(path),
        json:   data,
        params: params
      )
    end
  end
end

#request {|http| ... } ⇒ Common::Reponse

Allows to launch a different operation via block, providing the basic HTTP connection to the block.

Yields:

  • (http) —

    launch specific http request.

Yield Parameters:

  • http (HTTP) —

    the http connection.

Yield Returns:

Returns:

  • (Common::Reponse) —

    the basic custom response object.



136
137
138
 
# File 'lib/ecoportal/api/common/client.rb', line 136

def request
  wrap_response yield(base_request)
end

#url_for(path) ⇒ String

Full URl builder of the request

Parameters:

  • path (String) —

    the tail that completes the url of the request.

Returns:

  • (String) —

    the final url.



164
165
166
 
# File 'lib/ecoportal/api/common/client.rb', line 164

def url_for(path)
  "#{@base_uri}#{@version}#{path}"
end

#wrap_response(response) ⇒ Common::Reponse

Wrap with basic custom object of the gem for responses.

Parameters:

  • response (HTTP::Response)

Returns:

  • (Common::Reponse) —

    the basic custom response object.



143
144
145
 
# File 'lib/ecoportal/api/common/client.rb', line 143

def wrap_response(response)
  Ecoportal::API::Common::Response.new(response)
end