Class: CrAPI::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/crapi/client.rb

Overview

Provides a connection mechanism, simple CRUD methods (#delete / #get / #patch / #post / #put), and proxy generators.

Constant Summary collapse

JSON_CONTENT_TYPE =

The content-type for JSON data.

'application/json'.freeze
FORM_CONTENT_TYPE =

The content-type for FORM data.

'application/x-www-form-urlencoded'.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base_uri, opts = {}) ⇒ Client

Returns a new instance of Client.

Parameters:

  • base_uri (URI, String) —

    The base URI the client should use for determining the host to connect to, determining whether SSH is applicable, and setting the base path for subsequent CRUD calls.

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

    Method options. All method options are optional in this particular case.

Options Hash (opts):

  • :insecure (true, false) —

    Whether to allow insecure SSH connections (i.e. don't attempt to verify the validity of the given certificate).

  • :proxy_host (String) —

    The DNS name or IP address of a proxy server to use when connecting to the target system. Maps to Net::HTTP#new's p_addr.

  • :proxy_port (Number) —

    The proxy server port to use when connecting to the target system. Maps to Net::HTTP#new's p_port.

  • :proxy_username (String) —

    The username to give if authorization is required to access the specified proxy host. Maps to Net::HTTP#new's p_user.

  • :proxy_password (Number) —

    The password to give if authorization is required to access the specified proxy host. Maps to Net::HTTP#new's p_pass.

Raises:



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/crapi/client.rb', line 57

def initialize(base_uri, opts = {})
  @base_uri = case base_uri
              when URI then base_uri
              when String then URI(base_uri)
              else raise CrAPI::ArgumentError, %(Unexpected "base_uri" type: #{base_uri.class})
              end

  @proxy_host = opts[:proxy_host]
  @proxy_port = opts[:proxy_port]
  @proxy_username = opts[:proxy_username]
  @proxy_password = opts[:proxy_password]

  @http = Net::HTTP.new(@base_uri.host, @base_uri.port,
                        @proxy_host, @proxy_port, @proxy_username, @proxy_password)
  @http.use_ssl = (@base_uri.scheme == 'https')
  @http.verify_mode = ::OpenSSL::SSL::VERIFY_NONE if opts[:insecure].present?

  @default_headers = { 'Content-Type': JSON_CONTENT_TYPE }.with_indifferent_access
end

Instance Attribute Details

#default_headers ⇒ Object

A Hash containing headers to send with every request (unless overriden elsewhere). Headers set by the user via the CRUD methods' headers still override any conflicting default header.



17
18
19
 
# File 'lib/crapi/client.rb', line 17

def default_headers
  @default_headers
end

Instance Method Details

#delete(path, headers: {}, query: {}) ⇒ Object

CRUD method: DELETE

Parameters:

  • path (String) —

    The path to the resource to DELETE. Note that this path is always interpreted as relative to the client's base_uri's path, regardless of whether it begins with a "/".

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

    Additional headers to set in addition to the client's defaults. Any header given here and also appearing in the client's defaults will override said default value.

  • query (Hash, Array, String) (defaults to: {}) —

    Query string values, if any, to append to the given path. Strings are appended as-is; Hashes and Arrays are serialized as URI-encoded form data before appending.

Returns:

  • (Object) 


112
113
114
115
116
117
118
 
# File 'lib/crapi/client.rb', line 112

def delete(path, headers: {}, query: {})
  headers = @default_headers.merge(headers)

  response = @http.delete(full_path(path, query: query), headers)
  ensure_success!(response)
  parse_response(response)
end

#get(path, headers: {}, query: {}) ⇒ Object

CRUD method: GET

Parameters:

  • path (String) —

    The path to the resource to GET. Note that this path is always interpreted as relative to the client's base_uri's path, regardless of whether it begins with a "/".

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

    Additional headers to set in addition to the client's defaults. Any header given here and also appearing in the client's defaults will override said default value.

  • query (Hash, Array, String) (defaults to: {}) —

    Query string values, if any, to append to the given path. Strings are appended as-is; Hashes and Arrays are serialized as URI-encoded form data before appending.

Returns:

  • (Object) 


137
138
139
140
141
142
143
 
# File 'lib/crapi/client.rb', line 137

def get(path, headers: {}, query: {})
  headers = @default_headers.merge(headers)

  response = @http.get(full_path(path, query: query), headers)
  ensure_success!(response)
  parse_response(response)
end

#new_proxy(segment = '/', headers: nil) ⇒ CrAPI::Proxy

Returns a new CrAPI::Proxy for this client.

Parameters:

  • segment (String) (defaults to: '/') —

    The segment to add to this client's path.

  • headers (Hash) (defaults to: nil) —

    The default headers for the new proxy.

Returns:



89
90
91
 
# File 'lib/crapi/client.rb', line 89

def new_proxy(segment = '/', headers: nil)
  Proxy.new(add: segment, to: self, headers: headers)
end

#patch(path, headers: {}, query: {}, payload: {}) ⇒ Object

CRUD method: PATCH

Parameters:

  • path (String) —

    The path to the resource to PATCH. Note that this path is always interpreted as relative to the client's base_uri's path, regardless of whether it begins with a "/".

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

    Additional headers to set in addition to the client's defaults. Any header given here and also appearing in the client's defaults will override said default value.

  • query (Hash, Array, String) (defaults to: {}) —

    Query string values, if any, to append to the given path. Strings are appended as-is; Hashes and Arrays are serialized as URI-encoded form data before appending.

  • payload (Hash, String) (defaults to: {}) —

    The payload to send, if any. Strings are used as-is; Hashes are serialized per the request's "Content-Type" header.

Returns:

  • (Object) 


166
167
168
169
170
171
172
173
 
# File 'lib/crapi/client.rb', line 166

def patch(path, headers: {}, query: {}, payload: {})
  headers = @default_headers.merge(headers)
  payload = format_payload(payload, as: headers[:'Content-Type'])

  response = @http.patch(full_path(path, query: query), payload, headers)
  ensure_success!(response)
  parse_response(response)
end

#post(path, headers: {}, query: {}, payload: {}) ⇒ Object

CRUD method: POST

Parameters:

  • path (String) —

    The path to the resource to POST. Note that this path is always interpreted as relative to the client's base_uri's path, regardless of whether it begins with a "/".

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

    Additional headers to set in addition to the client's defaults. Any header given here and also appearing in the client's defaults will override said default value.

  • query (Hash, Array, String) (defaults to: {}) —

    Query string values, if any, to append to the given path. Strings are appended as-is; Hashes and Arrays are serialized as URI-encoded form data before appending.

  • payload (Hash, String) (defaults to: {}) —

    The payload to send, if any. Strings are used as-is; Hashes are serialized per the request's "Content-Type" header.

Returns:

  • (Object) 


196
197
198
199
200
201
202
203
 
# File 'lib/crapi/client.rb', line 196

def post(path, headers: {}, query: {}, payload: {})
  headers = @default_headers.merge(headers)
  payload = format_payload(payload, as: headers[:'Content-Type'])

  response = @http.post(full_path(path, query: query), payload, headers)
  ensure_success!(response)
  parse_response(response)
end

#put(path, headers: {}, query: {}, payload: {}) ⇒ Object

CRUD method: PUT

Parameters:

  • path (String) —

    The path to the resource to PATCH. Note that this path is always interpreted as relative to the client's base_uri's path, regardless of whether it begins with a "/".

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

    Additional headers to set in addition to the client's defaults. Any header given here and also appearing in the client's defaults will override said default value.

  • query (Hash, Array, String) (defaults to: {}) —

    Query string values, if any, to append to the given path. Strings are appended as-is; Hashes and Arrays are serialized as URI-encoded form data before appending.

  • payload (Hash, String) (defaults to: {}) —

    The payload to send, if any. Strings are used as-is; Hashes are serialized per the request's "Content-Type" header.

Returns:

  • (Object) 


226
227
228
229
230
231
232
233
 
# File 'lib/crapi/client.rb', line 226

def put(path, headers: {}, query: {}, payload: {})
  headers = @default_headers.merge(headers)
  payload = format_payload(payload, as: headers[:'Content-Type'])

  response = @http.put(full_path(path, query: query), payload, headers)
  ensure_success!(response)
  parse_response(response)
end