API
Description
Implements the common public API connection methods for custom rules & integrations.
By default the API uses SSL client certificates for authentication. Unified Assurance session authorization is mapped to the Global DefaultAPIUserID. If a non-default user is desired for authentication, passing credentials manually will overwrite using SSL client certificates.
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
new
Creates a new API object.
new(\%options)
Options
url -> Full or relative URL (eg. /api/devices/devices or https://assure1pres1.example.com/api/devices/devices)
webFQDN -> (optional) Override default primary presentation FQDN with custom option
sslClientCert -> (optional) {0,1} Disable default SSL client certificate authentication
configPath -> (optional) Path to a Assure1.conf if in non-standard location
Returns
API Object
Methods
create
Creates a record given correct parameters. When an API requires uploading files, the alternative format options must be used.
create(\%options)
Options
- Hash ref of key/value pairs defined by API call (typical)
- Array ref of key/value pairs when using form-data to upload file
The path to the filename must be an array ref value
Alternative Options
Content_Type -> indicates content type of upload, must be: 'form-data'
Content -> Array of PARAMS
Returns
Hash reference of 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 - Identifier for a single record
Returns
Hash reference of API response
Synopsis
my $response = $API->delete($id);
download
Downloads files to a SAVEFILE location
download($SaveFile [, \%Params])
Arguments
SaveFile -> File name location to save download to
Params -> (optional) Hash of key/value pairs defined by API call
Returns
Boolean for success of download
Synopsis
# download file
my $response = $API->download('/path/to/save/file', {
$property => $value
});
error
Return latest error
get
Similar to "read", but excludes optional ID. Used for Non-REST calls to a specific action
get([\%options])
getSessionData
Get session data for current session, or undef if no session is active
getSessionData
Returns
PHP Session data, contains the following keys:
- EmailAddress - string, user email
- FullName - string, user full name
- Locale - string, local e.g. "en_US"
- PasswordExpiration - int, epoch of password expiration
- Permissions - hash of allowed user permissions by package -> UI -> create/read/update/delete/execute
e.g. user has 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 e.g. "US/Central"
- ThemeDir - string, theme directory
- UserGroupID - int, User Group ID
- UserID - int, User ID
- Username - string, logged in username
Synopsis
my $sessiondata = $API->getSessionData();
getURL
Get the current URL
loginBasic
Login with HTTP Basic authentication.
loginBasic(\%options)
Options
WebPort -> (default 443)
WebHost -> FQDN of presentation server
WebRealm -> (defaults to Unified Assurance)
Username -> Unified Assurance login
Password -> Unified Assurance password
Returns
True value always. Basic authentication is checked during request.
Synopsis
$API->loginBasic({
WebHost => $webHost,
WebPort => $webPort,
WebRealm => $webRealm,
Username => $webUser,
Password => $webPass
});
loginSession
Login with REST authentication action and setup session. Uses the configured APIUser unless given a username and password to use.
loginSession(\%options)
Options
Username -> Unified Assurance login (Optional if sslClientCert is enabled)
Password -> Unified Assurance password (Optional if sslClientCert is enabled)
Returns
Boolean value depending on success or failure of login.
Synopsis
$API->loginSession();
OR
$API->loginSession({
Username => $webUser,
Password => $webPass
});
logoutSession
Logout with REST action and destroy session.
logoutSession
Returns
Boolean value depending on success or failure of logout.
Synopsis
$API->logoutSession();
post
Alias to "create". Used for Non-REST calls to a specific action
post(\%options)
read
Retrieves all records or one record (if $id specified) for a set API call.
Special limits may be applied with the parameter 'limit' when reading multiple records:
- no 'limit' parameter or 'limit' = 0: retrieve all records in a paginated fashion and return the aggregated results, this may impact performance but supports scale
- 'limit' = -1: no safety limits applied. WARNING: not recommended when expecting large datasets such as 5000 or more
- 'limit' > 0: Obtain given set of records and save state for subsequent calls to readNext() for next set of records;
read([$id] [, \%options])
Arguments
ID -> (optional) Identifier for a single record
Options -> (optional) Hash of key/value pairs defined by API call
Returns
Hash reference of 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
Initiates request for next set of records using last run read() call with a custom limit state if available. If no previous read has been called or there are no more records, will return undef.
readNext
Returns
Hash reference of API response or undef when 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
Change URL
setURL($url)
Arguments
URL - new url
update
Updates a record given correct parameters. When an API requires uploading files, the alternative format options must be used.
update($id [, \%options])
Arguments
ID -> Identifier for a single record
Options -> Hash of key/value pairs defined by API call (typical)
-> Array ref of key/value pairs when using form-data to upload file
The path to the filename must be an array ref value
Alternative Arguments
ID -> Identifier for a single record
Content_Type -> indicates content type of upload, must be: 'form-data'
Content -> Array of PARAMS
Returns
Hash reference of 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']
]
);