NAME
Net::Versa::Director - Versa Director REST API client library
VERSION
version 0.003000
SYNOPSIS
use v5.36;
use Net::Versa::Director;
# to use the username/password basic authentication
my $director = Net::Versa::Director->new(
server => 'https://director.example.com:9182',
user => 'username',
passwd => '$password',
clientattrs => {
timeout => 10,
},
);
# OR to use the OAuth token based authentication
$director = Net::Versa::Director->new(
server => 'https://director.example.com:9183',
user => 'username',
passwd => '$password',
clientattrs => {
timeout => 10,
},
);
# this is required to fetch the OAuth access and refresh tokens
# using the client id and secret passed to user and passwd.
$director->login;
# at the end of your code, possible in an END block to always execute it
# after a successful login to not exceed the maximum number of access
# tokens.
$director->logout;DESCRIPTION
This module is a client library for the Versa Director REST API using the basic authentication API endpoint on port 9182.
Currently it is developed and tested against version 21.2.
For more information see https://docs.versa-networks.com/Management_and_Orchestration/Versa_Director/Director_REST_APIs/01_Versa_Director_REST_API_Overview.
METHODS
login
Takes a client id and secret.
Logs into the Versa Director when using the OAuth token based port 9183.
Sets the Authorization header to the Bearer access token.
Returns a hashref containing the OAuth access- and refresh-tokens.
logout
Revokes the access token if OAuth authentication is used so the maximum number of access tokens of the client isn't exceeded.
Returns the response.
get_director_info
Returns the Versa Director information as hashref.
From /api/operational/system/package-info.
get_version
Returns the Versa Director version.
From "get_director_info"->{branch}.
list_appliances
Returns an arrayref of Versa appliances.
From /vnms/appliance/appliance.
list_device_workflows
Returns an arrayref of device workflows.
From /vnms/sdwan/workflow/devices.
get_device_workflow
Takes a workflow name.
Returns a hashref of device workflow data.
From /vnms/sdwan/workflow/devices/device/$device_workflow_name.
list_assets
Returns an arrayref of Versa appliances.
From /vnms/assets/asset.
list_device_interfaces
Takes a device name.
Returns an arrayref of interface hashrefs.
From /api/config/devices/device/$devicename/config/interfaces/vni?deep.
list_device_networks
Takes a device name.
Returns an arrayref of network hashrefs.
From /api/config/devices/device/$devicename/config/networks/network?deep=true.
ERROR handling
All methods throw an exception on error returning the unmodified data from the API as hashref.
Currently the Versa Director has to different API error formats depending on the type of request.
authentication errors
The response of an authentication error looks like this:
{
code => 4001,
description => "Invalid user name or password.",
http_status_code => 401,
message => "Unauthenticated",
more_info => "http://nms.versa.com/errors/4001",
}YANG data model errors
All API endpoints starting with /api/config or /api/operational return this type of error:
YANG and relational data model errors
All API endpoints starting with /vnms return this type of error:
{
error => "Not Found",
exception => "com.versa.vnms.common.exception.VOAEException",
http_status_code => 404,
message => " device work flow non-existing does not exist ",
path => "/vnms/sdwan/workflow/devices/device/non-existing",
timestamp => 1696574964569,
}TESTS
To run the live API tests the following environment variables need to be set:
- NET_VERSA_DIRECTOR_HOSTNAME
- NET_VERSA_DIRECTOR_USERNAME
- NET_VERSA_DIRECTOR_PASSWORD
- NET_VERSA_DIRECTOR_CLIENT_ID
- NET_VERSA_DIRECTOR_CLIENT_SECRET
If basic authentication tests should be also run set this additional variable to true.
- NET_VERSA_DIRECTOR_BASIC_AUTH
Only read calls are tested so far.
AUTHOR
Alexander Hartmaier <abraxxa@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2025 by Alexander Hartmaier.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.