SOAP Examples Using Perl (API)

Understanding How The API Works

Perl Examples – Sample Zone Commands

Here’s a PERL example using SOAP::WSDL and the libraries from wsdl2perl.pl to:

Log in to the API to establish a Session [SessionLogin]
Get a List of existing Zones [GetZones]
Create a new zone [CreateZone]
Add A Records and MX Records [CreateARecord CreateMXRecord]
Create a new node with an A record [CreateARecord]
Publish the Zone [PublishZone]
Logout [SessionLogout]

Click to view the example code.


#! /usr/bin/perl -lw
#
# A simple example script for SOAP::WSDL 
# local libraries generated with 
#     wsdl2perl.pl -b ./lib https://api2.dynect.net/wsdl/3.0.0/Dynect.wsdl

use lib './lib';

use MyInterfaces::Dynect::DynectSOAP;

my $debug = 0; # control some output

# create our interface client
my $interface = MyInterfaces::Dynect::DynectSOAP->new();

my $auth = {
        'customer_name' => $customer_name,
		'user_name' => $user_name,
        'password' => $password,
        'fault_incompat' => 1, # some libs choke on the SOAP-FAULT envelope
};


# login
my $response = $interface->SessionLogin($auth);
&check_fault($response);

# check the status of the call
unless ($response->get_status() eq "success") { 
	&output_messages($response);
	# can't continue without a login token
	exit(1);
}

# need the token for all calls, so let's get it
my $token = $response->get_data()->get_token();

print "Login Status: " . $response->get_status() if $debug;
print "Login Token: " . $token if $debug;

# args we always need
my $args = {
	'token' => $token,
	'fault_incompat' => 1,
};

# simple Get a List of existing zones
$response = $interface->GetZones($args);
&check_fault($response);

my $zones = $response->get_data();
if ($debug) {
	for my $zone (@$zones) { 
		print "Zone: " . $zone->get_zone();
	}
}

# let's create a zone
my $zone_args = {
	'zone' => 'api' . &genRandomString(5) . '.net',
	'ttl'  => 3600, # default tll for all records
	'rname' => 'hostmaster@firstzoneapi.com', # responsible party
	%$args, # we always need these
};

$response = $interface->CreateZone($zone_args);
&check_fault($response);

unless ($response->get_status() eq "success") { 
	print ">>> Create Zone:";
	&output_messages($response);
}

my $zone_name = $response->get_data()->get_zone();
print $zone_name if $debug;

# add some standard records
# A record at the root
$response = $interface->CreateARecord( { 
	token =>  $token,
	fault_incompat => 1,  
	fqdn => $zone_name,
	zone =>  $zone_name,
	ttl =>  '3600',
	rdata =>  { 
		address => '192.16.12.13',
	},
},);
&check_fault($response);

unless ($response->get_status() eq "success") { 
	print ">>> Create A Record:";
	&output_messages($response);
}


# MX Records at the root
my $mx_args = {
	fqdn =>  $zone_name,
	zone =>  $zone_name,
	rdata =>  { 
		preference =>  10,
		exchange =>  'gmail.google.com',
		},
	%$args,
};

$response = $interface->CreateMXRecord($mx_args);
&check_fault($response);

unless ($response->get_status() eq "success") { 
	print ">>> Create MX Record";
	&output_messages($response);
}

$mx_args->{'rdata'} = {'preference' => 20, exchange => 'mail.dyndns.com'};

$response = $interface->CreateMXRecord($mx_args);
&check_fault($response);

unless ($response->get_status() eq "success") { 
	&output_messages($response);
}


# publish that zone
$response = $interface->PublishZone(
	{ %$args,
	'zone' => $zone_name,
	},
);
&check_fault($response);

unless ($response->get_status() eq "success") { 
	&output_messages($response);
}

# let's add a new node with an A record
$response = $interface->CreateARecord( { 
	token =>  $token,
	fault_incompat => 1,  
	fqdn => 'www.' . $zone_name,
	zone =>  $zone_name,
	ttl =>  '3600',
	rdata =>  { 
		address => '192.116.112.113',
	},
},);
&check_fault($response);

unless ($response->get_status() eq "success") { 
	print ">>> Create A Record at www node:";
	&output_messages($response);
}

 
# publish that zone
$response = $interface->PublishZone(
	{ %$args,
	'zone' => $zone_name,
	},
);
&check_fault($response);

unless ($response->get_status() eq "success") { 
	&output_messages($response);
}

#  an example of a bad call, and the response
#  the error here is that the fqdn (host name) is not in the same zone
#  as the zone argument
my $cname_args = {
	%$args,
	'fqdn' => 'web1.' . $zone_name,
	'zone' => 'boguszone.com',
	'ttl'  => '60',
	'rdata' => { cname => 'www.' . $zone_name,},
};

$response = $interface->CreateCNAMERecord($cname_args);
&check_fault($response);
unless ($response->get_status() eq "success") { 
	print ">>> Create CNAME Record:";
	&output_messages($response);
}

#logout
$response = $interface->SessionLogout( $args );
unless ($response->get_status() eq "success") { 
	&output_messages($response);
}
print "<<<<< All Done >>>>>>>\n";

# some helper functions
=pod
check_fault 
	evaluates the SOAP response for SOAP::WSDL::SOAP::Typelib::Fault11
	SOAP::WSDL::SOAP::Typelib::Fault11 objects are false in boolean context
	for 'fault_incompat' libraries,  the way to get this info is from the
		response->get_status() which will be 'failure', then 
		check the messages

output_messages 
	will print out any messages returned from the API

=cut

sub check_fault {
	my $response = shift;
	if (!$response) {
		die "Error calling SOAP method: ", $response->get_faultstring();
	}
}

sub output_messages {
	my $response = shift;
	
	print "Got a status code of " . $response->get_status();
	my $messages = $response->get_msgs();

	foreach $message (@$messages) {
		print "message:";
		print "  source: " . $message->get_source();
		print "  lvl: " . $message->get_lvl();
		print "  err_cd: " . $message->get_err_cd() if $message->get_err_cd();
		print "  info: " . $message->get_info();
	}
}

sub genRandomString {
	my ($max_length) = @_;
	$max_length ||= 10;
	return join('', map { chr(int(rand(26)) + ord('a')) } (1..$max_length));
}

Perl Examples – Sample RTTM Create

Here’s a PERL example using SOAP::WSDL and the libraries from wsdl2perl.pl to:

Log in to the API to establish a Session [SessionLogin]
Create an RTTM service on a new node [CreateRTTM]
Note: This script assumes an existing published zone in DynECT
Examine some of the information about the new service
Logout [SessionLogout]

Click to view the example code.

#! /usr/bin/perl -lw
#
# A simple example script for SOAP::WSDL rttm
# local libraries generated with 
#	wsdl2perl.pl -b ./lib https://api2.dynect.net/wsdl/3.0.0/Dynect.wsdl 

use lib './lib';

use MyInterfaces::Dynect::DynectSOAP;

# create our interface client
my $interface = MyInterfaces::Dynect::DynectSOAP->new();

my $auth = {
        'customer_name' => $customer_name,
		'user_name' => $user_name,
        'password' => $password,
        'fault_incompat' => 1, # some libs choke on the SOAP-FAULT envelope
};


# login
my $response = $interface->SessionLogin($auth);
&check_fault($response);

# check the status of the call
unless ($response->get_status() eq "success") { 
	&output_messages($response);
	# can't continue without a login token
	exit(1);
}

# need the token for all calls, so let's get it
my $token = $response->get_data()->get_token();

# args we always need
my $args = {
	'token' => $token,
	'fault_incompat' => 1,
};

# define the parameters for the RTTM service
my $zone = 'apitest.com'; # an existing, published zone in Dynect
my $host = 'rttm';
my $fqdn = join '.' , $host , $zone;

my $pool = [ # define the array of address to monitor/serve
 { 
	 'address' => '1.2.3.4',
	 'serve_mode' => 'obey',
 },
 { 
	 'address' => '2.2.3.4',
	 'serve_mode' => 'obey',
 },
 { 
	 'address' => '3.2.3.4',
	 'serve_mode' => 'obey',
 },
 { 
	 'address' => '4.2.3.4',
	 'serve_mode' => 'obey',
 },
 { 
	 'address' => '5.2.3.4',
	 'serve_mode' => 'obey',
 },
];

my $global_region = { 
	'region_code' => 'global', 
	'failover_mode' => 'ip', 
	'failover_data' => '127.0.0.1', 
	'serve_count' => 2, 
	'pool_count' => 4, 
	'failover_count' => 1, 
	'pool' => $pool,
};

# monitoring interval in minutes
my $health_monitor = { 'protocol' => 'PING', 'interval' => 1, };
my $performance_monitor = { 'protocol' => 'HTTP', 'interval' => 10, };

# ok, build up the service args
my $rttm_args = {
	'zone' => $zone,
	'fqdn' => $fqdn,
	'ttl'  => '30', # must be < .5 * $health_monitor->{'interval'}
	'notify_events' => 'ip,svc', # when to send notifications
	'contact_nickname' => 'api', # existing contact nickname
	'region' => [ $global_region, ],
	'monitor' => $health_monitor,
	'performance_monitor' =>  $performance_monitor, 
	'token' => $token,
	'fault_incompat' => 1,
};


$response = $interface->CreateRTTM($rttm_args);
&check_fault($response);

# check the status of the call
unless ($response->get_status() eq "success") { &output_messages($response); } 

my $rttm_add = $response->get_data();

my $perf_mon = $rttm_add->get_performance_monitor();
print $perf_mon;

# since in this instance the global pool will automatically populate the regions
# let's grab the global pool and examine some data
#
my $regions = $rttm_add->get_region;
for my $r (@$regions) {
	next unless $r->get_region_code eq 'global';
	$global_region = $r;
}

print "Pool Count: " . $global_region->get_pool_count;
print "Region Status: " . $global_region->get_status;



#logout
$response = $interface->SessionLogout( $args );
unless ($response->get_status() eq "success") { 
	&output_messages($response);
}
print "<<<<< All Done >>>>>>>\n";

# some helper functions
=pod
check_fault 
	evaluates the SOAP response for SOAP::WSDL::SOAP::Typelib::Fault11
	SOAP::WSDL::SOAP::Typelib::Fault11 objects are false in boolean context
	for 'fault_incompat' libraries,  the way to get this info is from the
		response->get_status() which will be 'failure', then 
		check the messages

output_messages 
	will print out any messages returned from the API

=cut

sub check_fault {
	my $response = shift;
	if (!$response) {
		die "Error calling SOAP method: ", $response->get_faultstring();
	}
}

sub output_messages {
	my $response = shift;
	
	print "Got a status code of " . $response->get_status();
	my $messages = $response->get_msgs();

	foreach $message (@$messages) {
		print "message:";
		print "  source: " . $message->get_source();
		print "  lvl: " . $message->get_lvl();
		print "  err_cd: " . $message->get_err_cd() if $message->get_err_cd();
		print "  info: " . $message->get_info();
	}
}

sub genRandomString {
	my ($max_length) = @_;
	$max_length ||= 10;
	return join('', map { chr(int(rand(26)) + ord('a')) } (1..$max_length));
}

Perl Examples – Sample Get RTTM Commands

Here’s a PERL example using SOAP::WSDL and the libraries from wsdl2perl.pl to:

Log in to the API to establish a Session [SessionLogin]
Get details of an existing RTTM Service [GetOneRTTM]
Examine some of the data
Logout [SessionLogout]

Click to view the example code.


#! /usr/bin/perl -lw
#
# A simple example script for SOAP::WSDL rttm
# local libraries generated with 
#	wsdl2perl.pl -b ./lib https://api2.dynect.net/wsdl/3.0.0/Dynect.wsdl 

use lib './lib';

use MyInterfaces::Dynect::DynectSOAP;

# create our interface client
my $interface = MyInterfaces::Dynect::DynectSOAP->new();

my $auth = {
	'customer_name' => $customer_name,
	'user_name' => $nser_name,
	'password' => $password,
	'fault_incompat' => 1, # some libs choke on the SOAP-FAULT envelope
};


# login
my $response = $interface->SessionLogin($auth);
&check_fault($response);

# check the status of the call
unless ($response->get_status() eq "success") { 
	&output_messages($response);
	# can't continue without a login token
	exit(1);
}

# need the token for all calls, so let's get it
my $token = $response->get_data()->get_token();

# args we always need
my $args = {
	'token' => $token,
	'fault_incompat' => 1,
};

# define the parameters for the RTTM service
my $zone = 'apitest.com'; # an existing, published zone in Dynect
my $host = 'rttm'; # host with an existing RTTM service
my $fqdn = join '.' , $host , $zone;

my $rttm_args = {
	%$args,
	zone => $zone,
	fqdn => $fqdn,
};

print ">>>> Calling GetOneRTTM <<<<<<";

$response = $interface->GetOneRTTM($rttm_args);
&check_fault($response);

# check the status of the call
unless ($response->get_status() eq "success") { &output_messages($response); } 

print "Examine some bits of the Response: ";
print "Monitor: " . $response->get_data()->get_monitor();

my $region = $response->get_data()->get_region();

for my $r (@$region) {
	print "Regsion: " . $r->get_region_code();
	print "Regsion Status: " . $r->get_status();
}

#logout
$response = $interface->SessionLogout( $args );
unless ($response->get_status() eq "success") { 
	&output_messages($response);
}
print "<<<<< All Done >>>>>>>\n";

# some helper functions
=pod
check_fault 
	evaluates the SOAP response for SOAP::WSDL::SOAP::Typelib::Fault11
	SOAP::WSDL::SOAP::Typelib::Fault11 objects are false in boolean context
	for 'fault_incompat' libraries,  the way to get this info is from the
		response->get_status() which will be 'failure', then 
		check the messages

output_messages 
	will print out any messages returned from the API

=cut

sub check_fault {
	my $response = shift;
	if (!$response) {
		die "Error calling SOAP method: ", $response->get_faultstring();
	}
}

sub output_messages {
	my $response = shift;
	
	print "Got a status code of " . $response->get_status();
	my $messages = $response->get_msgs();

	foreach $message (@$messages) {
		print "message:";
		print "  source: " . $message->get_source();
		print "  lvl: " . $message->get_lvl();
		print "  err_cd: " . $message->get_err_cd() if $message->get_err_cd();
		print "  info: " . $message->get_info();
	}
}

sub genRandomString {
	my ($max_length) = @_;
	$max_length ||= 10;
	return join('', map { chr(int(rand(26)) + ord('a')) } (1..$max_length));
}

Perl Examples – Get Message Infomation

A <msgs> element is a list of zero or more messages with sub-elements

SOURCE: A debugging field. If reporting an error to your Dynect Concierge, be sure to include this.
LEVEL: The severity of the message. One of: ‘FATAL’, ‘ERROR’, ‘WARN’, or ‘INFO’
INFO: The actual message itself.
ERR_CD: An error code (if appropriate) regarding the message.

Here’s an example of a Perl utility function to take a response and gather info from each of the messages element (uses SOAP::WSDL get_DATA methods)

Click to view the example code.

sub output_messages {
	my $response = shift;

	print "Got a status code of " . $response->get_status();

	# grab a reference to the list of messages
	my $messages = $response->get_msgs();

	foreach $message (@$messages) {
		print "message:";
		print "  source: " . $message->get_source();
		print "  lvl: " . $message->get_lvl();
		print "  info: " . $message->get_info();
		print "  err_cd: " . $message->get_err_cd() if $message->get_err_cd();
	}
}

In the case of a successful call, the will contain only one element, SOAP::WSDL helpfully flatten this for you, so you can access the message INFO thusly:


$result->get_msgs()->get_info();

or

my $messages = $response->get_msgs();
$message->get_info();

DNS API Knowledge Base