Assure1::API Perl library¶

Description¶

Implements the common public API connection methods for custom rules & integrations.

By default the API uses SSL client certificates for authentication. Assure1 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 authetication and use one of the login\* methods manually
my $API = Assure1::API->new({
    url           => $url,
    sslClientCert => 0
});

# OR

# Basic usage for non-Assure1 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 Assure1
    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 Assure1)
Username -> Assure1 login - (eg. admin)
Password -> Assure1 password (eg. admin)

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 -> Assure1 login - (e.g. admin)  (Optional if sslClientCert is enabled)
Password -> Assure1 password (e.g. admin) (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']
    ]
);