Class: Aspire::API::JSON

Inherits:
Base
  • Object
show all
Defined in:
lib/aspire/api/json.rb

Overview

A wrapper class for the Aspire JSON API

Constant Summary collapse

API_ROOT =

The default API root URL

"https://#{ASPIRE_DOMAIN}".freeze
API_ROOT_AUTH =

The default authentication API root URL

"https://#{ASPIRE_AUTH_DOMAIN}/1/oauth/tokens".freeze

Constants inherited from Base

Base::ASPIRE_AUTH_DOMAIN, Base::ASPIRE_DOMAIN, Base::SCHEME, Base::SSL_OPTS, Base::TALIS_DOMAIN

Instance Attribute Summary collapse

Attributes inherited from Base

#logger, #ssl, #tenancy_code, #timeout

Instance Method Summary collapse

Constructor Details

#initialize(api_client_id = nil, api_secret = nil, tenancy_code = nil, **opts) ⇒ void

Initialises a new API instance

Parameters:

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

    the API client ID

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

    the API secret associated with the client ID

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

    the Aspire short tenancy code

  • opts (Hash) —

    API customisation options

Options Hash (**opts):

  • :api_root (String) —

    the base URL of the Aspire JSON APIs

  • :api_root_auth (String) —

    the base URL of the Aspire Persona authentication API

  • :api_version (Integer) —

    the version of the Aspire JSON APIs

  • :logger (Logger) —

    a logger for activity logging

  • :timeout (Integer) —

    the API call timeout period in seconds



53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/aspire/api/json.rb', line 53

def initialize(api_client_id = nil, api_secret = nil, tenancy_code = nil,
               **opts)
  super(tenancy_code, **opts)
  @api_client_id = api_client_id
  @api_secret = api_secret
  @api_token = nil
  self.api_root = opts[:api_root] || API_ROOT
  self.api_root_auth = opts[:api_root_auth] || API_ROOT_AUTH
  self.api_version = opts[:api_version] || 2
  rate_limit
end

Instance Attribute Details

#api_root ⇒ String

Returns the base URL of the Aspire JSON APIs.

Returns:

  • (String) —

    the base URL of the Aspire JSON APIs



17
18
19
 
# File 'lib/aspire/api/json.rb', line 17

def api_root
  @api_root
end

#api_root_auth ⇒ String

Returns the base URL of the Aspire Persona authentication API.

Returns:

  • (String) —

    the base URL of the Aspire Persona authentication API



21
22
23
 
# File 'lib/aspire/api/json.rb', line 21

def api_root_auth
  @api_root_auth
end

#api_version ⇒ Integer

Returns the version of the Aspire JSON APIs.

Returns:

  • (Integer) —

    the version of the Aspire JSON APIs



25
26
27
 
# File 'lib/aspire/api/json.rb', line 25

def api_version
  @api_version
end

#rate_limit=(value) ⇒ Object

Sets the attribute rate_limit

Parameters:

  • value —

    the value to set the attribute rate_limit to.



29
30
31
 
# File 'lib/aspire/api/json.rb', line 29

def rate_limit
  @rate_limit
end

#rate_remaining ⇒ Integer

Returns the rate remaining value from the most recent API call (the number of calls remaining within the current limit period).

Returns:

  • (Integer) —

    the rate remaining value from the most recent API call (the number of calls remaining within the current limit period)



34
35
36
 
# File 'lib/aspire/api/json.rb', line 34

def rate_remaining
  @rate_remaining
end

#rate_reset ⇒ Integer

Returns the rate reset value from the most recent API call (the time in seconds since the Epoch until the next limit period).

Returns:

  • (Integer) —

    the rate reset value from the most recent API call (the time in seconds since the Epoch until the next limit period)



39
40
41
 
# File 'lib/aspire/api/json.rb', line 39

def rate_reset
  @rate_reset
end

Instance Method Details

#api_url(path) ⇒ String

Returns a full Aspire JSON API URL. Full URLs are returned as-is, partial endpoint paths are expanded with the API root, version and tenancy code.

Parameters:

  • path (String) —

    the full URL or partial endpoint path

Returns:

  • (String) —

    the full JSON API URL



70
71
72
73
 
# File 'lib/aspire/api/json.rb', line 70

def api_url(path)
  return path if path.include?('//')
  "#{api_root}/#{api_version}/#{tenancy_code}/#{path}"
end

#call(path, headers: nil, options: nil, payload: nil, **params) {|response, data| ... } ⇒ Hash

Calls an Aspire JSON API method and returns the parsed JSON response Additional keyword parameters are passed as query string parameters to the API call.

Parameters:

  • path (String) —

    the path of the API call

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

    HTTP headers for the API call

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

    options for the REST client

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

    the data to post to the API call

Yields:

  • (response, data) —

    Passes the REST client response and parsed JSON hash to the block

Yield Parameters:

  • the (RestClient::Response) —

    REST client response

  • the (Hash) —

    parsed JSON data from the response

Returns:

  • (Hash) —

    the parsed JSON content from the API response



87
88
89
90
91
92
93
94
 
# File 'lib/aspire/api/json.rb', line 87

def call(path, headers: nil, options: nil, payload: nil, **params)
  rest_options = call_rest_options(path,
                                   headers: headers, options: options,
                                   payload: payload, params: params)
  response, data = call_api_with_auth(**rest_options)
  yield(response, data) if block_given?
  data
end