Class: LUSI::API::Core::API

Inherits:
Object
  • Object
show all
Defined in:
lib/lusi_api/core/api.rb

Overview

Provides a wrapper for the LUSI web service API

Instance Method Summary collapse

Constructor Details

#initialize(api_user: nil, api_password: nil, api_root: nil, logger: nil, timeout: nil) ⇒ API

Initializes a new API instance

Parameters:

  • api_user (String) (defaults to: nil) —

    the service account username

  • api_password (String) (defaults to: nil) —

    the service account password

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

    a Logger instance for optional logging

  • timeout (Integer) (defaults to: nil) —

    the timeout in seconds for LUSI API calls



22
23
24
25
26
27
28
 
# File 'lib/lusi_api/core/api.rb', line 22

def initialize(api_user: nil, api_password: nil, api_root: nil, logger: nil, timeout: nil)
  @api_password = api_password
  @api_root = api_root || 'https://lusiservice.lancs.ac.uk'
  @api_user = api_user
  @logger = logger
  @timeout = timeout.to_i
end

Instance Method Details

#call(path, endpoint, method, headers: nil, options: nil, **params) ⇒ Nokogiri::XML::Node Also known as: post

Calls a LUSI API method and return the parsed XML response Any undocumented keyword parameters are passed as parameters to the LUSI API call. The LUSI ‘Username’ and ‘Password’ parameters are automatically added.

Parameters:

  • path (String) —

    the path of the API call (e.g. ‘LUSIReference’)

  • endpoint (String) —

    the endpoint of the API call (e.g. ‘General.asmx’)

  • method (String) —

    the method name of the API call (e.g. ‘GetServiceAccountDetails’)

  • headers (Hash<String, String>) (defaults to: nil) —

    optional HTTP headers for the API call

  • options (Hash<String, Object>) (defaults to: nil) —

    options for the REST client

Returns:

  • (Nokogiri::XML::Node) —

    the parsed XML <body> content from the API response

Raises:

  • (LUSIAPI::Core::APITimeoutError) —

    if the LUSI API call times out

  • (LUSIAPI::Core::APICallError) —

    if the LUSI API call fails for any other reason (e.g. network unavailable)

  • (LUSIAPI::Core::APIContentError) —

    if the LUSI API call returns an XML document with an error response



42
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
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/lusi_api/core/api.rb', line 42

def call(path, endpoint, method, headers: nil, options: nil, **params)

  # Add the username and password to the params
  params[:Username] ||= @api_user
  params[:Password] ||= @api_password

  # Set the REST client headers
  rest_headers = {}.merge(headers || {})

  # Set the REST client options
  rest_options = {
      method: :post,
      headers: rest_headers,
      payload: params,
      url: url(path, endpoint, method),
  }
  rest_options[:timeout] = @timeout if @timeout > 0
  rest_options.merge(options) if options

  RestClient.log = @log if @log

  # Make the API call
  begin
    response = RestClient::Request.execute(**rest_options)
  rescue RestClient::Exceptions::Timeout => e
    raise APITimeoutError.new(url: rest_options[:url])
  rescue RestClient::Exception => e
    raise APICallError.new(url: rest_options[:url])
  rescue => e
    raise APIError.new(url: rest_options[:url])
  end

  # Extract and return the XML content
  xml(response)

end

#get_service_account_details ⇒ LUSI::API::ServiceAccount

Return a ServiceAccount instance representing the API’s service user

Returns:



81
82
83
84
85
 
# File 'lib/lusi_api/core/api.rb', line 81

def 
  # There should only be one instance but get_instance returns an array for consistnecy with other classes
  result = LUSI::API::ServiceAccount.get_instance(self)
  result.length == 0 ? nil : result[0]
end

#update_service_account_password(password = nil) ⇒ String

Update the service user’s password via the LUSI API

Parameters:

  • password (String, nil) (defaults to: nil) —

    the new password (a random 16-character password is generated if this is omitted)

Returns:

  • (String) —

    the new password



94
95
96
 
# File 'lib/lusi_api/core/api.rb', line 94

def (password = nil)
  @api_password = LUSI::API::ServiceAccount.(self, password)
end

#url(path = nil, endpoint = nil, method = nil) ⇒ String

Construct a full API method URL from its constituents

Parameters:

  • path (String) (defaults to: nil) —

    the path of the API call (e.g. ‘LUSIReference’)

  • endpoint (String) (defaults to: nil) —

    the endpoint of the API call (e.g. ‘General.asmx’)

  • method (String) (defaults to: nil) —

    the method name of the API call (e.g. ‘GetServiceAccountDetails’)

Returns:

  • (String) —

    the fully-qualified URL of the API method



103
104
105
 
# File 'lib/lusi_api/core/api.rb', line 103

def url(path = nil, endpoint = nil, method = nil)
  "#{@api_root}/#{path}/#{endpoint}/#{method}"
end