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:

  • command (String) —

    the command to execute

  • check_res_body (Boolean) (defaults to: true) —

    whenever to check the response body

  • payload —

    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 ⇒ RestClient::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:

  • args (Array<Mixed>) —

    the initializer arguments

  • kwargs (Hash{Symbol => Mixed}) —

    the initializer arguments

Returns:

  • (RestClient::Response) —

    the API call response



114
115
116
 
# File 'lib/jabber_admin/api_call.rb', line 114

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

.perform! ⇒ RestClient::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:

  • args (Array<Mixed>) —

    the initializer arguments

  • kwargs (Hash{Symbol => Mixed}) —

    the initializer arguments

Returns:

  • (RestClient::Response) —

    the API call response

Raises:

  • JabberAdmin::ApiError

  • JabberAdmin::CommandError



128
129
130
 
# File 'lib/jabber_admin/api_call.rb', line 128

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.

rubocop:disable Metrics/AbcSize – because its the bundled check logic rubocop:disable Metrics/MethodLength – ditto

Raises:

  • JabberAdmin::ApiError

  • JabberAdmin::CommandError



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/jabber_admin/api_call.rb', line 56

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 == '0'
end

#perform ⇒ RestClient::Response

Just a simple DSL wrapper for the response method.

Returns:

  • (RestClient::Response) —

    the API call response



91
92
93
 
# File 'lib/jabber_admin/api_call.rb', line 91

def perform
  response
end

#perform! ⇒ RestClient::Response

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

Returns:

  • (RestClient::Response) —

    the API call response

Raises:

  • JabberAdmin::ApiError

  • JabberAdmin::CommandError



102
103
104
105
 
# File 'lib/jabber_admin/api_call.rb', line 102

def perform!
  check_response
  response
end

#response ⇒ RestClient::Response

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

Returns:

  • (RestClient::Response) —

    the response of the API call



36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/jabber_admin/api_call.rb', line 36

def response
  @response ||= RestClient::Request.execute(
    method: :post,
    url: url,
    user: JabberAdmin.configuration.username,
    password: JabberAdmin.configuration.password,
    payload: payload.to_json
  )
rescue RestClient::Exception => e
  @response = e.response
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 trailling slash, or not.

Returns:

  • (String) —

    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