Class: Usps::Imis::Api

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

Overview

The core API wrapper

Constant Summary collapse

AUTHENTICATION_PATH =

Endpoint for (re-)authentication requests

'Token'
API_PATH =

Endpoint for general API requests

'api'
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



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

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



32
33
34
 
# File 'lib/usps/imis/api.rb', line 32

def imis_id
  @imis_id
end

#token ⇒ Object (readonly)

API bearer token



22
23
24
 
# File 'lib/usps/imis/api.rb', line 22

def token
  @token
end

#token_expiration ⇒ Object (readonly)

Expiration time for the API bearer token

Used to automatically re-authenticate as needed



28
29
30
 
# File 'lib/usps/imis/api.rb', line 28

def token_expiration
  @token_expiration
end

Instance Method Details

#delete(business_object_name, url_id: nil) ⇒ String

Remove a business object for the current member

Parameters:

  • business_object_name (String) —

    Name of the business object

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

    Override the ID param of the URL (e.g. used for Panels)

Returns:

  • (String) —

    Error response body from the API, or empty string on success



150
151
152
153
154
155
 
# File 'lib/usps/imis/api.rb', line 150

def delete(business_object_name, url_id: nil)
  uri = uri_for(business_object_name, url_id:)
  request = Net::HTTP::Delete.new(uri)
  result = submit(uri, authorize(request))
  result.body
end

#get(business_object_name, url_id: nil) ⇒ Hash

Get a business object for the current member

Parameters:

  • business_object_name (String) —

    Name of the business object

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

    Override the ID param of the URL (e.g. used for Panels)

Returns:

  • (Hash) —

    Response data from the API



91
92
93
94
95
96
 
# File 'lib/usps/imis/api.rb', line 91

def get(business_object_name, url_id: nil)
  uri = uri_for(business_object_name, url_id:)
  request = Net::HTTP::Get.new(uri)
  result = submit(uri, authorize(request))
  JSON.parse(result.body)
end

#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



58
59
60
61
62
63
 
# File 'lib/usps/imis/api.rb', line 58

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

#instance_variables_to_inspect ⇒ Object

Ruby 3.5 instance variable filter



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

def instance_variables_to_inspect = %i[@token_expiration @imis_id]

#mapper ⇒ Object

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



175
176
177
 
# File 'lib/usps/imis/api.rb', line 175

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

#panels ⇒ Object

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



182
183
184
185
186
187
 
# File 'lib/usps/imis/api.rb', line 182

def panels
  @panels ||= Struct.new(:vsc, :education).new(
    Panel::Vsc.new(self),
    Panel::Education.new(self)
  )
end

#post(business_object_name, body, url_id: nil) ⇒ Hash

Create a business object for the current member

Parameters:

  • business_object_name (String) —

    Name of the business object

  • body (Hash) —

    Full raw API object data

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

    Override the ID param of the URL (e.g. used for Panels)

Returns:

  • (Hash) —

    Response data from the API



135
136
137
138
139
140
141
 
# File 'lib/usps/imis/api.rb', line 135

def post(business_object_name, body, url_id: nil)
  uri = uri_for(business_object_name, url_id:)
  request = Net::HTTP::Post.new(uri)
  request.body = JSON.dump(body)
  result = submit(uri, authorize(request))
  JSON.parse(result.body)
end

#put(business_object_name, body, url_id: nil) ⇒ Hash

Update a business object for the current member

Parameters:

  • business_object_name (String) —

    Name of the business object

  • body (Hash) —

    Full raw API object data

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

    Override the ID param of the URL (e.g. used for Panels)

Returns:

  • (Hash) —

    Response data from the API



119
120
121
122
123
124
125
 
# File 'lib/usps/imis/api.rb', line 119

def put(business_object_name, body, url_id: nil)
  uri = uri_for(business_object_name, url_id:)
  request = Net::HTTP::Put.new(uri)
  request.body = JSON.dump(body)
  result = submit(uri, authorize(request))
  JSON.parse(result.body)
end

#put_fields(business_object_name, fields, url_id: nil) ⇒ Hash

Update only specific fields on a business object for the current member

Parameters:

  • business_object_name (String) —

    Name of the business object

  • fields (Hash) —

    Conforms to pattern { field_key => value }

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

    Override the ID param of the URL (e.g. used for Panels)

Returns:

  • (Hash) —

    Response data from the API



106
107
108
109
 
# File 'lib/usps/imis/api.rb', line 106

def put_fields(business_object_name, fields, url_id: nil)
  updated = filter_fields(business_object_name, fields)
  put(business_object_name, updated, url_id:)
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



164
165
166
167
168
169
170
171
 
# File 'lib/usps/imis/api.rb', line 164

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

#update(data) ⇒ Object

Convenience alias for updating mapped fields



191
192
193
 
# File 'lib/usps/imis/api.rb', line 191

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

#with(id) ⇒ Object

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

This should be used with methods that do not change the value of ‘imis_id`

Examples:

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

Parameters:

  • id (Integer, String) —

    iMIS ID to select for requests within the block



76
77
78
79
80
81
82
 
# File 'lib/usps/imis/api.rb', line 76

def with(id, &)
  old_id = imis_id
  self.imis_id = id
  instance_eval(&)
ensure
  self.imis_id = old_id
end