ABSTRACT

This class can be used by batch jobs which want to communicate with VIP objects through a REST interface.


SYNOPSIS

 #!/usr/bin/perl
 use VipInterface;
 my $server = VipInterface->connect( -server => 'https://127.0.0.1/~vip/cgi-bin/rest',
                                     -login_script=>'login.cgi',
                                     -username=>'vipuser',
                                     -password=>'secret' );
 if ($server->error_msg) {
     print "code      : " . $server->code ."\n";
     print "error_msg : " . $server->error_msg ."\n";
     print "focus     : " . $server->focus ."\n";
     die "Can not connect to server\n";
 }
 print "Connected: " . $server->success . "\n";
 print "\n--------------- get_user_list\n";
 my $response = $server->get( 'user/get_user_list.cgi', validated_by => 'nethz' );
 if ($response->error_msg) {
     print "code      : " . $response->code ."\n";
     print "error_msg : " . $response->error_msg ."\n";
     print "focus     : " . $response->focus ."\n";
 } else {
     my $labels = $response->labels;
     print join( "\t", @$labels ), "\n";
     while ( my $row = $response->next_row_array ) {
         print join( "\t", @$row ), "\n";
     }
 }


METHODS

Server Object

VipInterface->connect( ... )
Connects to the VIP application. Arguments:
-server=>$base_url
Specifies the base URL of the VIP applications REST interface.

-login_script=>$relativ_url
Specifies the script which handels validation.

-username=>$username
The user should be registred with a vip_id on the Vip database (see Users.pm) and a role should be granted to that user, which gives him the rest property (see Roles.pm and Properties.pm).

-password=>$plaintext_pw
Used for validation.

The connect method returns a server object, which can be used to access the VIP application.

The server object has methods code, error_msg, focus and success which report about success or errors of the connect method.

There is also a get method which is used to generate requests to the VIP REST application and returns ressponse objects.

$server->code
Returns a false value, if the connection was successful. Otherwise a HTTP status code, of which the most common are:
 404 not found (base_url/relativ_url not found)
 500 a validation error (username/password not found, or the username has no
     role which gives him the rest prpoerty.

$server->focus
Only relevant if $server->code returns 500: the offending parameter (username or password) or a '-' when an error occured, which can not be associated with one of the arguments.

$server->error_msg
Returns a false value if the connection was successful. Otherwise an error message.

$server->success
Returns a false value if the connection was not successful. Otherwise a message (like 'your last login was on ...');

Making a Request gets you a Response Objects

The server object has the method get which makes a request to the VIP application and returns a response object. The response has a error/success report and a table of data. Each row of the table is a data set (an objects data). The columns are labeled: labels should conform to Perl naming conventions. There are methods to iterate through the response data row be row; each row can be retrieved as a hash or an array.

$response = $server->get( $url, name1=>'val1', name2=>'val2' ...);
$url should be a relativ URL (base was specified with the connect method.

All other arguments are passed to the script as named paramters.

The response object has methods code, error_msg, focus and success which report about success or errors of the get method. Methods next_row_hash and next_row_array iterate through the response data, reset_iterator resets the iterator and method labels returns the column headings.