NAME
Net::Versa::Director - Versa Director REST API client library
VERSION
version 0.005000
SYNOPSIS
use v5.38;
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.
Currently it is developed and tested against version 22.1.4.
For more information see https://docs.versa-networks.com/Management_and_Orchestration/Versa_Director/Director_REST_APIs/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 a hashref of interface types each containing an arrayref of interface hashrefs.
From /api/config/devices/device/$devicename/config/interfaces?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.
get_device_configuration
Takes a device name.
Returns the current device configuration as string.
From /vnms/appliance/export?applianceName=$devicename.
ERROR handling
All methods throw an exception on error returning the unmodified data from the API as a Net::Versa::Director::Exception subclass object which stringifies to an error message.
Currently the Versa Director has multiple different API error formats depending on the type of request.
See https://docs.versa-networks.com/Management_and_Orchestration/Versa_Director/Director_REST_APIs/Versa_Director_REST_API_Overview#Status_and_Error_Responses for a detailed documentation about the possible error responses.
OAuth errors
Are thrown as Net::Versa::Director::Exception::OAuth objects and have the following attributes:
error => 'invalid_client',
error_description =>'Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).',YANG data model errors
All API endpoints starting with /api/config or /api/operational return this type of error. They are thrown as Net::Versa::Director::Exception::Basic objects and have the following attributes:
code => 401,
description => "Invalid user name or password.",
http_status_code => 401,
message => "Unauthenticated",
more_info => "http://nms.versa.com/errors/401",YANG and relational data model errors
All API endpoints starting with /vnms are thrown as Net::Versa::Director::Exception::VNMS objects:
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,other errors
If an error response doesn't conform to any of the above documented types, the exception is thrown as Net::Versa::Director::Exception::Other object:
http_status_code => 500,
message => "500 Internal Server Error",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 <alex@hartmaier.priv.at>
COPYRIGHT AND LICENSE
This software is copyright (c) 2023 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.