Class: Usps::Imis::Api

Inherits:
Object
  • Object
show all
Includes:
Requests
Defined in:
lib/usps/imis/api.rb

Overview

The core API wrapper

Constant Summary collapse

AUTHENTICATION_PATH =

Endpoint for (re-)authentication requests

'Token'
QUERY_PATH =

Endpoint for IQA query requests

'api/Query'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(skip_authentication: false, imis_id: nil) ⇒ Api

A new instance of Api

Parameters:

  • skip_authentication (bool) (defaults to: false) —

    Skip authentication on initialization (used for tests)

  • imis_id (Integer, String) (defaults to: nil) —

    iMIS ID to select immediately on initialization



45
46
47
48
 
# File 'lib/usps/imis/api.rb', line 45

def initialize(skip_authentication: false, imis_id: nil)
  authenticate unless skip_authentication
  self.imis_id = imis_id if imis_id
end

Instance Attribute Details

#imis_id ⇒ Object

Currently selected iMIS ID for API requests



34
35
36
 
# File 'lib/usps/imis/api.rb', line 34

def imis_id
  @imis_id
end

#lock_imis_id ⇒ Object (readonly)

Whether to lock changes to the selected iMIS ID



38
39
40
 
# File 'lib/usps/imis/api.rb', line 38

def lock_imis_id
  @lock_imis_id
end

#token ⇒ Object (readonly)

API bearer token



24
25
26
 
# File 'lib/usps/imis/api.rb', line 24

def token
  @token
end

#token_expiration ⇒ Object (readonly)

Expiration time for the API bearer token

Used to automatically re-authenticate as needed



30
31
32
 
# File 'lib/usps/imis/api.rb', line 30

def token_expiration
  @token_expiration
end

Instance Method Details

#imis_id_for(certificate) ⇒ String

Convert a member’s certificate number into an iMIS ID number

Parameters:

  • certificate (String) —

    Certificate number to lookup the corresponding iMIS ID for

Returns:

  • (String) —

    Corresponding iMIS ID

Raises:



66
67
68
69
70
71
72
73
74
75
 
# File 'lib/usps/imis/api.rb', line 66

def imis_id_for(certificate)
  raise Errors::LockedIdError if lock_imis_id

  begin
    result = query(Imis.configuration.imis_id_query_name, { certificate: })
    @imis_id = result['Items']['$values'][0]['ID']
  rescue StandardError
    raise Errors::NotFoundError, 'Member not found'
  end
end

#instance_variables_to_inspect ⇒ Object

Ruby 3.5 instance variable filter



174
 
# File 'lib/usps/imis/api.rb', line 174

def instance_variables_to_inspect = %i[@token_expiration @imis_id]

#mapper ⇒ Object

An instance of Mapper, using this instance as its parent Api



155
156
157
 
# File 'lib/usps/imis/api.rb', line 155

def mapper
  @mapper ||= Mapper.new(self)
end

#on(business_object_name, ordinal: nil) ⇒ Object

Run requests as DSL, with specific BusinessObject only maintained for this scope

If no block is given, this returns the specified BusinessObject.

Parameters:

  • business_object_name (String) —

    Name of the business object

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

    Ordinal to build override ID param of the URL (e.g. used for Panels)



146
147
148
149
150
151
 
# File 'lib/usps/imis/api.rb', line 146

def on(business_object_name, ordinal: nil, &)
  object = BusinessObject.new(self, business_object_name, ordinal:)
  return object unless block_given?

  object.instance_eval(&)
end

#panels ⇒ Object

Convenience accessor for available Panel objects, each using this instance as its parent Api



168
169
170
 
# File 'lib/usps/imis/api.rb', line 168

def panels
  @panels ||= Panels.all(self)
end

#query(query_name, query_params = {}) ⇒ Hash

Run an IQA Query

Parameters:

  • query_name (String) —

    Full path of the query in IQA, e.g. $/_ABC/Fiander/iMIS_ID

Returns:

  • (Hash) —

    Response data from the API



111
112
113
114
115
116
117
118
 
# File 'lib/usps/imis/api.rb', line 111

def query(query_name, query_params = {})
  query_params[:QueryName] = query_name
  path = "#{QUERY_PATH}?#{query_params.to_query}"
  uri = URI(File.join(Imis.configuration.hostname, path))
  request = Net::HTTP::Get.new(uri)
  result = submit(uri, authorize(request))
  JSON.parse(result.body)
end

#query_all(query_name, query_params = {}) ⇒ Array<Hash>

Run an IQA Query, paging through all responses

Parameters:

  • query_name (String) —

    Full path of the query in IQA, e.g. $/_ABC/Fiander/iMIS_ID

Returns:

  • (Array<Hash>) —

    Collected response item values from the API



127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/usps/imis/api.rb', line 127

def query_all(query_name, query_params = {})
  response = query(query_name, **query_params)
  results = response['Items']['$values']

  while response['HasNext']
    response = query(query_name, **query_params, Offset: response['NextOffset'])
    results += response['Items']['$values']
  end

  results
end

#update(data) ⇒ Object

Convenience alias for updating mapped fields



161
162
163
 
# File 'lib/usps/imis/api.rb', line 161

def update(data)
  mapper.update(data)
end

#with(id) ⇒ Object

Run requests as DSL, with specific iMIS ID only maintained for this scope

While in this block, changes to the value of imis_id are not allowed

If no block is given, this sets the iMIS ID and returns self.

Examples:

with(12345) do
  update(mm: 15)
end

Parameters:

  • id (Integer, String) —

    iMIS ID to select for requests within the block



90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/usps/imis/api.rb', line 90

def with(id, &)
  old_id = imis_id
  self.imis_id = id
  return self unless block_given?

  @lock_imis_id = true
  instance_eval(&)
ensure
  if block_given?
    @lock_imis_id = false
    self.imis_id = old_id
  end
end