API
The API library implements the common public API connection methods for custom rules and integrations.
By default, the API uses SSL client certificates for authentication. Unified Assurance session authorization is mapped to the global DefaultAPIUserID. To use a non-default user for authentication, pass credentials manually.
Synopsis
use Assure1::API;
# Default
my $API = Assure1::API->new({
url => $url
});
# OR
# Prevent SSL client authentication and use one of the login\* methods manually
my $API = Assure1::API->new({
url => $url,
sslClientCert => 0
});
# OR
# Basic usage for non-Unified Assurance sites
my $API = Assure1::API->new({
url => $url,
webFQDN => 'http://www.example.com',
sslClientCert => 0
});
# HTTP Basic authentication
$API->loginBasic({
WebHost => $webHost, # Defaults to primary WebFQDN
WebPort => $webPort, # Defaults to 443
WebRealm => $webRealm, # Defaults to Unified Assurance
Username => $webUser,
Password => $webPass
});
# OR
# REST session login
$API->loginSession({
Username => $webUser,
Password => $webPass
});
# API call
my $response = $API->read();
# Check errors in call
if (!defined $response) {
warn 'Error: ' . $API->error() . "\\n";
}
# Check for successful response
elsif (!$response->{success}) {
warn 'API error: ' . $response->{message} . "\\n";
}
# Do something with data
else {
print Dumper($response->{data}) . "\\n";
}
# REST session logout, if loginSession called earlier
$API->logoutSession();
Constructor
The API library contains the constructor described below.
new
Creates a new API object.
new(\%options)
Options
url - Full or relative URL (for example, /api/devices/devices or https://uapres.example.com/api/devices/devices)
webFQDN - (optional) A custom FQDN that overrides the FQDN of the default primary presentation server.
sslClientCert - (optional) Set to 0 to disable the default SSL client certificate authentication. Set to 1 to enable it.
configPath - (optional) The path to Assure1.conf if it is in non-standard location
Returns
API Object
Methods
The API library contains the methods described below.
create
Creates a record when given correct parameters. When an API requires uploading files, use the alternative options (Content_Type and Content).
create(\%options)
Options
- Typically, a hash ref of key/value pairs defined by the API call.
- Alternatively, an array ref of key/value pairs under Content when using form-data to upload a file
The path to the filename must be an array ref value
Alternative Options
Content_Type - Indicates the content type of upload. Must be: form-data
Content - Array of parameters in key/value pairs, including the path to the file to upload.
Returns
Hash reference of the API response.
Synopsis
# Typical create
my $response = $API->create({
$paramKey1 => $paramValue1,
$paramKey2 => $paramValue2
});
OR
# File upload create
my $response = $API->create(
Content_Type => 'form-data',
Content => [
$paramKey1 => $paramValue1,
$paramKey2 => $paramValue2,
$uploadParam => ['/path/to/file']
]
);
delete
Deletes one record of a given ID for a set API call.
delete($id)
Arguments
ID - The identifier for the single record to delete.
Returns
Hash reference of the API response.
Synopsis
my $response = $API->delete($id);
download
Downloads files to the location specified in SaveFile.
download($SaveFile [, \%Params])
Arguments
SaveFile - The location to save the download to.
Params - (optional) The hash of key/value pairs defined by the API call.
Returns
Boolean indicating whether the download succeeded.
Synopsis
# download file
my $response = $API->download('/path/to/save/file', {
$property => $value
});
error
Returns the latest error.
get
Similar to "read", but excludes the optional ID. Used for non-REST calls to a specific action.
get([\%options])
getSessionData
Gets session data for the current session, or returns undef if no session is active.
getSessionData
Returns
PHP session data containing the following keys:
- EmailAddress - String, user email
- FullName - String, user full name
- LicenseExpired - Boolean, whether license is expired
- Locale - String, locale. For example, en_US.
- PasswordExpiration - Integer, epoch time of password expiration
- Permissions - Hash of allowed user permissions (create/read/update/delete/execute) by package.
For example, a user with permission to read only their User Profile:
{
coreAAA => {
UserProfiles => {
read => 1
}
}
...
}
- Preferences - Hash of user preference settings
- Properties - Hash of user property settings
- TZ - String, time zone. For example, US/Central.
- ThemeDir - String, theme directory
- UserGroupID - Integer, user group ID
- UserID - Integer, user ID
- Username - String, logged in username
Synopsis
my $sessiondata = $API->getSessionData();
getURL
Gets the current URL.
loginBasic
Logs in with HTTP Basic authentication.
loginBasic(\%options)
Options
WebPort - Port. The default is 443.
WebHost - The FQDN of the presentation server.
WebRealm - (defaults to Assure1)
Username - A Unified Assurance user to log in.
Password - The password of the Unified Assurance user to log in.
Returns
True value always. Basic authentication is checked during request.
Synopsis
$API->loginBasic({
WebHost => $webHost,
WebPort => $webPort,
WebRealm => $webRealm,
Username => $webUser,
Password => $webPass
});
loginSession
Logs in with REST authentication action and sets up a session. Uses the configured APIUser unless a different user name and password are specified.
loginSession(\%options)
Options
Username - The Unified Assurance user to log in with. (Optional if sslClientCert is enabled.)
Password - The password for the Unified Assurance user to log in with. (Optional if sslClientCert is enabled)
Returns
Boolean value indicating whether the login succeeded.
Synopsis
$API->loginSession();
OR
$API->loginSession({
Username => $webUser,
Password => $webPass
});
logoutSession
Logs out with REST action and destroys the session.
logoutSession
Returns
Boolean value indicating whether the logout was successful.
Synopsis
$API->logoutSession();
post
Alias to "create". Used for Non-REST calls to a specific action.
post(\%options)
read
Retrieves all records or the record that matches the specified ID for a set API call.
Set the limit parameter as follows to apply limits when reading multiple records:
- 0: Retrieves all records in a paginated fashion and returns the aggregated results. This is the default behavior that applies if you do not include the limit parameter. This may impact performance but supports scale.
- -1: No limits applied. Use this option only if you expect small datasets. Oracle recommends setting limits when you expect large datasets, such as 5000 or more.
- Integers greater than 0: Retrieves the specified number of records and saves their state for subsequent "readNext" calls to get the next set of records.
read([$id] [, \%options])
Arguments
ID - (optional) The ID for a single record.
Options - (optional) The hash of key/value pairs defined by API call
Returns
Hash reference of the API response.
Synopsis
# Read all
my $response = $API->read();
# Read all sorted
my $response = $API->read(undef, {
sort => [{
property => $fieldName,
direction => 'ASC'
}]
});
# Read all filtered
my $response = $API->read(undef, {
filter => [{
property => $fieldName,
value => $value,
operator => 'like'
}]
});
# Read one by ID
my $response = $API->read($id);
readNext
Requests the next set of records using last "read" call, with any available custom limit state. If no previous read has been called or there are no more records, returns undef.
readNext
Returns
Hash reference of the API response or undef when no previous read has been called or there are no more records.
Synopsis
# prime by reading first set of 100 records with filters
my $response = $API->read(undef, {
limit => 100,
start => 0,
filter => [{
property => $fieldName,
value => $value,
operator => 'like'
}]
});
# process and read next set and continue until done
while ($response) {
stuff()
$response = $api->readNext();
}
setURL
Changes the URL.
setURL($url)
Arguments
URL - The new URL.
update
Updates a record when given correct parameters. When an API requires uploading files, use the alternative options (Content_Type and Content).
update($id [, \%options])
Arguments
ID - The identifier for the record to update.
Options - Typically, a hash of key/value pairs defined by API call.
- Alternatively, an array ref of key/value pairs under Content when using form-data to upload file.
The path to the filename must be an array ref value.
Alternative Arguments
ID - The identifier for the record to update.
Content_Type - The content type of the upload. This must be form-data.
Content - Array of parameters in key/value pairs, including the path to the file to upload.
Returns
Hash reference of the API response.
Synopsis
# Typical update
my $response = $API->update($id, {
$paramKey1 => $paramValue1,
$paramKey2 => $paramValue2
});
OR
# File upload update
my $response = $API->update($id,
Content_Type => 'form-data',
Content => [
$paramKey1 => $paramValue1,
$paramKey2 => $paramValue2,
$uploadParam => ['/path/to/file']
]
);