Migrating scripts from older 3.x API Core versions should be relatively painless. For scripts that are unlikely to see new development and just need to work, consider using the NetMRI::API::Client compatibility layer. To do this you don't need to change anything in your script. You can even take advantage of some features of the new interface while using the compatibility layer.

There are some advantages to migrating old code to use the new interface. The new interface is somewhat more efficient without the compatibility layer and is more succinct for common tasks, such as operating over a list of objects.

Api_version is Required

The constructor parameter api_version to NetMRI::API is required. By providing an api_version you guarantee your script will continue to function as expected as the NetMRI API evolves in the future. You may pass 'auto' as the argument to indicate that you really do want the API to detect the latest version available to both the Perl API and the NetMRI system. This indicates to the API that you understand that your script may behave differently when connecting to future versions of NetMRI.

my $client = new NetMRI::API::Client;

becomes either

my $client = new NetMRI::API(api_version => 'auto' );

or

my $client = new NetMRI::API(api_version => );

Naming Conventions

The current API uses the most common Perl naming conventions. Constructor arguments and accessor methods are lower-case under-score separated.

my $client = new NetMRI::API::Client(UserName => 'admin', Password => 'secret');

becomes

my $client = new NetMRI::API({ username => 'admin', password => 'secret',
api_version => 3.X });

Passing Arguments as a Hash Reference

The new 3.0 API encourages you to pass arguments as a hash reference instead of a list (which later gets converted into a hash anyway). Passing arguments as a list are still supported to maintain backward compatibility but are deprecated.

$client->index( DeviceID => 2 )

becomes

$client->index({ DeviceID => 2 })

Accessors

Remote object classes have accessor functions for retrieving field values, instead of treating them as a hash. The old behavior of treating these objects as a hash is supported because of the way remote object classes are implemented, but depending on this behavior is deprecated.

$device→{DeviceID}

becomes

$device→DeviceID

Broker Objects

Broker objects are cached by the $client object. This simplifies code when the same broker objects are used in different parts of the code.

my $broker = $client→get_broker('Device');

my $device1 = $broker->show( DeviceID => 1 );

my $device2 = $broker->show( DeviceID => 2 );

becomes

my $device1 = $client->get_broker('Device')->show( DeviceID => 1 );

my $device2 = $client->get_broker( 'Device')->show( DeviceID => 2 );

In addition, a new syntax for retrieving broker objects can be used:

my $device1 = $client->broker->device->show( DeviceID => 1 );

my $device2 = $client->broker->device->show( DeviceID => 2 );

List Methods

Some methods, such as index, return a list of remote objects. In the old interface, you could pass RetrieveAllPages => 1 as an argument to these list methods to get all objects, if the number of objects is greater than the page size. In the new interface, you can get the list of all objects by calling the method in the list context.

my $response = $client->get_broker('Interface')->index( RetrieveAllPages => 1);
foreach my $interface (@{ $response->{interfaces} })
{
print $interface->ifName,"\n";
}

becomes

foreach my $interface ($client->broker->interface->index)
{
print $interface->ifName, "\n";
}

Attaching Files

The current API retains the following syntax from previous releases for attaching files.

use NetMRI::API::Client;

my $client = new NetMRI::API::Client;

$client->get_broker('DiscoverySetting')->import( file=> 'LOCAL_FILE:file.txt', import_type => 'range',

);

becomes

use NetMRI::API qw( netmri_api_file );

my $client = new NetMRI::API::Client;

$client->broker->discovery_setting->import( file=> netmri_api_file 'file.txt', import_type => 'range',
);

If netmri_api_file is too verbose you can also simply import a file instead.

use NetMRI::API qw( file );

my $client = new NetMRI::API::Client;

$client->broker->discovery_setting->import( file=> file 'file.txt', import_type => 'range',

);

In the 3.0 API, use NetMRI::API::FindItfor for interacting with the NetMRI appliance's FindIt interface.

use NetMRI::API::Client;

my $client = new NetMRI::API::Client;

my $findit = $client→get_broker('FindIt');

my @result = $findit→find('foo');

becomes either

use NetMRI::API;

my $client = new NetMRI::API(api_version => 3.X );

my @result = $client→findit('foo');

or:

use NetMRI::API::FindIt;

my $findit = new NetMRI::API::FindIt( url=> 'http://netmri', username => 'admin',

password => 'secret',

);

my @result = $findit->find('foo');