Class: JabberAdmin::ApiCall

Inherits:
Object
  • Object
show all
Defined in:
lib/jabber_admin/api_call.rb

Overview

Handles a single communication with the API. An instance persists the response when performed once. So you can get the response multiple times, without repeating the request.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(command, check_res_body: true, **payload) ⇒ ApiCall

Setup a new API call instance with the given command and the given request payload.

Parameters:

  • the command to execute

  • (defaults to: true)

    whenever to check the response body

  • the request payload, empty by default



16
17
18
19
20
 
# File 'lib/jabber_admin/api_call.rb', line 16

def initialize(command, check_res_body: true, **payload)
  @command = command
  @payload = payload
  @check_res_body = check_res_body
end

Instance Attribute Details

#check_res_body ⇒ Object (readonly)

Returns the value of attribute check_res_body.



8
9
10
 
# File 'lib/jabber_admin/api_call.rb', line 8

def check_res_body
  @check_res_body
end

#command ⇒ Object (readonly)

Returns the value of attribute command.



8
9
10
 
# File 'lib/jabber_admin/api_call.rb', line 8

def command
  @command
end

#payload ⇒ Object (readonly)

Returns the value of attribute payload.



8
9
10
 
# File 'lib/jabber_admin/api_call.rb', line 8

def payload
  @payload
end

Class Method Details

.perform ⇒ HTTP::Response

A simple class level shortcut of the perform method. This is just DSL code which accepts the same arguments as the instance initialize method. (+#new+)

Parameters:

  • the initializer arguments

  • the initializer arguments

Returns:

  • the API call response

Raises:

  • on connection failures or timeouts



122
123
124
 
# File 'lib/jabber_admin/api_call.rb', line 122

def self.perform(*, **)
  new(*, **).perform
end

.perform! ⇒ HTTP::Response

A simple class level shortcut of the perform! method. This is just DSL code which accepts the same arguments as the instance initialize method. (+#new+)

Parameters:

  • the initializer arguments

  • the initializer arguments

Returns:

  • the API call response

Raises:

  • JabberAdmin::ApiError

  • JabberAdmin::CommandError

  • on connection failures or timeouts



137
138
139
 
# File 'lib/jabber_admin/api_call.rb', line 137

def self.perform!(*, **)
  new(*, **).perform!
end

Instance Method Details

#check_response ⇒ Object

Check if the response was successful. Otherwise raise exceptions with JabberAdmin::Exception as base type.

Raises:

  • JabberAdmin::ApiError

  • JabberAdmin::CommandError



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/jabber_admin/api_call.rb', line 63

def check_response
  # The REST API responds a 404 status code when the command is not known.
  if response.code == 404
    raise UnknownCommandError.new("Command '#{command}' is not known",
                                  response)
  end

  # In case we send commands with missing data or any other validation
  # issues, the REST API will respond with a 400 Bad Request status
  # code.
  raise CommandError.new('Invalid arguments for command', response) \
    if response.code == 400

  # Looks like the ejabberd REST API is returning 200 OK in case the
  # request was valid and permitted. But it does not indicate that the
  # request was successful handled. This is indicated on the response body
  # as a one (1) or a zero (0). (0 on success, 1 otherwise)
  raise RequestError.new('Response code was not 200', response) \
    unless response.code == 200

  # Stop the check, when we should not check the response body
  return unless check_res_body

  # The command was not successful, for some reason. Unfortunately we do
  # not get any further information here, which makes error debugging a
  # struggle.
  raise CommandError.new('Command was not successful', response) \
    unless response.body.to_s == '0'
end

#client ⇒ HTTP::Session

Build a ready to use HTTP client for the API call. It carries the configured administrator credentials as HTTP basic authentication and the configured request timeout, when one is set.

Returns:

  • the prepared HTTP client



36
37
38
39
40
41
 
# File 'lib/jabber_admin/api_call.rb', line 36

def client
  config = JabberAdmin.configuration
  session = HTTP.basic_auth(user: config.username, pass: config.password)
  session = session.timeout(config.timeout) if config.timeout
  session
end

#perform ⇒ HTTP::Response

Just a simple DSL wrapper for the response method.

Returns:

  • the API call response

Raises:

  • on connection failures or timeouts



97
98
99
 
# File 'lib/jabber_admin/api_call.rb', line 97

def perform
  response
end

#perform! ⇒ HTTP::Response

Just a simple DSL wrapper for the response method. But this variant performs a response check which will raise exceptions when there are issues.

Returns:

  • the API call response

Raises:

  • JabberAdmin::ApiError

  • JabberAdmin::CommandError

  • on connection failures or timeouts



109
110
111
112
 
# File 'lib/jabber_admin/api_call.rb', line 109

def perform!
  check_response
  response
end

#response ⇒ HTTP::Response

This method compose the actual request, performs it and stores the response to the instance. Additional calls to this method will not repeat the request, but will deliver the response directly.

The payload is sent as a JSON document. The response body is read right away, so the response is complete and the connection is closed when we hand it out. Any status code is delivered as a regular response, only connection failures and timeouts raise.

Returns:

  • the response of the API call

Raises:

  • on connection failures or timeouts



54
55
56
 
# File 'lib/jabber_admin/api_call.rb', line 54

def response
  @response ||= client.post(url, json: payload).flush
end

#url ⇒ String

The resulting URL of the API call. This URL is constructed with the JabberAdmin.configuration.url as base and the command name as the suffix. The configuration is allowed to end with trailing slash, or not.

Returns:

  • the API call URL



27
28
29
 
# File 'lib/jabber_admin/api_call.rb', line 27

def url
  "#{JabberAdmin.configuration.url.strip.chomp('/')}/#{@command}"
end