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

Inherits:
Object
  • Object
show all
Defined in:
lib/ecoportal/api/common/client.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)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, version: "v1", host: "live.ecoportal.com", logger: nil) ⇒ 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: "v1") —

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

  • host (String) (defaults to: "live.ecoportal.com") —

    api server domain.

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

    an object with Logger interface to generate logs.



21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/ecoportal/api/common/client.rb', line 21

def initialize(api_key:, version: "v1", host: "live.ecoportal.com", logger: nil)
  @version  = version
  @api_key  = api_key
  @logger   = logger
  if host.match(/^localhost|^127\.0\.0\.1/)
    @base_uri = "http://#{host}/api/"
  else
    @base_uri = "https://#{host}/api/"
  end
  log(:info) { "#{version} client initialized pointing at #{host}" }
  if @api_key.nil? || @api_key.match(/\A\W*\z/)
    log(:error) { "Api-key missing!" }
  end
  @response_logging_enabled = true
end

Instance Attribute Details

#logger ⇒ Logger

the logger.

Returns:

  • (Logger) —

    the current value of logger



12
13
14
 
# File 'lib/ecoportal/api/common/client.rb', line 12

def logger
  @logger
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 param to the header.

Returns:

  • (HTTP) —

    HTTP object.



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

def base_request
  @base_request ||= HTTP.headers("X-ApiKey" => @api_key).accept(:json)
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.



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

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.



58
59
60
61
62
63
64
 
# File 'lib/ecoportal/api/common/client.rb', line 58

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

#log(level) { ... } ⇒ Object

Logger interface. @example: log(:info) information on what's going on" log(:warn) is a warning that something is likely to have gone amiss" log(:error) went wrong" log(:fatal) unrecoverable error has happend"

Parameters:

  • level (Symbol) —

    the level that the message should be logged.

Yields:

  • [] generates the message.

Yield Returns:

  • (String) —

    the generated message.



46
47
48
 
# File 'lib/ecoportal/api/common/client.rb', line 46

def log(level, &block)
  logger.send(level, &block) if logger
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.



86
87
88
89
90
91
92
 
# File 'lib/ecoportal/api/common/client.rb', line 86

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:) ⇒ 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.

Returns:

  • (Common::Reponse) —

    the basic custom response object.



72
73
74
75
76
77
78
 
# File 'lib/ecoportal/api/common/client.rb', line 72

def post(path, data:)
  instrument("POST", path, data) do
    request do |http|
      http.post(url_for(path), json: data)
    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.



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

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.



132
133
134
 
# File 'lib/ecoportal/api/common/client.rb', line 132

def url_for(path)
  @base_uri+@version+path
end

#without_response_logging(&block) ⇒ Object 



136
137
138
139
140
141
142
143
 
# File 'lib/ecoportal/api/common/client.rb', line 136

def without_response_logging(&block)
  begin
    @response_logging_enabled = false
    yield self
  ensure
    @response_logging_enabled = true
  end
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.



118
119
120
 
# File 'lib/ecoportal/api/common/client.rb', line 118

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