| Net::OpenSRS(3pm) | User Contributed Perl Documentation | Net::OpenSRS(3pm) |
Net::OpenSRS - Domain registration via the Tucows OpenSRS HTTPS XML API
This is a wrapper interface to the DNS portions of the Tucows OpenSRS HTTPS XML API.
The client library distributed by OpenSRS can be difficult to integrate into a custom environment, and their web interface becomes quickly tedious with heavy usage. This is a clean and relatively quick library to perform the most common API methods described in the OpenSRS API documentation.
use Net::OpenSRS;
my $key = 'Your_API_Key_From_The_Reseller_Interface';
my $srs = Net::OpenSRS->new();
$srs->environment('live');
$srs->set_key( $key );
$srs->set_manage_auth( 'manage_username', 'manage_password' );
my $cookie = $srs->get_cookie( 'spime.net' );
if ($cookie) {
print "Cookie: $cookie\n";
} else {
print $srs->last_response() . "\n";
}
# do a batch of domain locks
$srs->bulk_lock([ 'example.com', 'example.net', ... ]);
# renew a domain
my $result = $srs->renew_domain( 'example.com' );
...
This module requires some setup in the OpenSRS reseller environment before it will work correctly.
OpenSRS allows for a variety of ways to organize your domains. Because of this, writing a 'one size fits all' module is rather difficult. Instead, we make a few assumptions regarding the way people use their OpenSRS reseller accounts.
**** These assumptions will ultimately determine if this module is right for you! Please read them carefully! ****
For example, 'spime.net' is my master management account. Before doing any register_domain() calls, I call master_domain('spime.net') - then any transfers or registrations from that point forward are linked to 'spime.net'. If a customer wants access to the SRS web management interface, I can then just create a subaccount for just their domain, so I retain absolute control -- in the event a customer forgets their password, I'm covered.
This library defaults to the TEST environment. (horizon.) Many API methods don't work in the test environment (SET COOKIE being the most notable example, as any API method relying on a cookie doesn't work either.) Neither does batch processing. Most everything else should be ok. ( See environment() )
Many methods require customer information. I leave the method of fetching this information entirely to you. All examples below that show a $c variable expect a hashref (or object) that contain these keys:
my $c = {
firstname => 'John',
lastname => 'Doe',
city => 'Portland',
state => 'Oregon',
country => 'US',
address => '555 Someplace Street',
email => 'john@example.com',
phone => '503-555-1212',
company => 'n/a'
};
my $srs = Net::OpenSRS->new();
Create a new Net::OpenSRS object. There are no options for this method.
Debugging is off by default. When called without an argument, returns the current debug level.
Note that it is reset on each method call.
Returns the last OpenSRS return code and result string, or if passed any true value, instead returns the full XML (parsed into a hashref) of the last OpenSRS return. (perfect for Data::Dumper)
Examples:
200: Command Successful
400: Domain example.com does not exist with OpenSRS
$srs->set_manage_auth( $username, $password );
Set the owner management username and password. This is used to fetch cookies, and perform any API methods that require the management cookie. For specifics on this, see the OpenSRS API documentation.
set_key() is affected by the current environment(). Calling the set_key() method while in the test environment only sets the key for the test environment - likewise for the live environment. To set a key for the live environment, you need to call environment('live') first.
my $env = $srs->environment;
$srs->environment('live');
Without an argument, returns a string - either 'test', or 'live', depending on the environment the object is currently using.
The test environment is the default.
If passed an argument (either 'test' or 'live') - switches into the desired environment. You will need to set_key() if you were previously using a different environment, or if you hadn't set_key() yet.
my $master = $srs->master_domain;
$srs->master_domain('spime.net');
Without an argument, returns the currently set 'master domain' account. Otherwise, it sets the master domain.
New transfers and registrations are linked under this domain, for centralized management. See the 'Assumptions' section, above.
my $result = $srs->bulk_lock([ 'example.com', 'example.net' ]);
Returns remote bulk queue id on successful batch submission.
my $result = $srs->check_queued_request( $queue_id );
Requires queue id - returned from batch methods such as bulk_lock(). Always returns hashref of queue command on success. Check $srs->last_response() for status progress.
my $result = $srs->check_transfer( 'example.com' );
Checks the status of a transfer in progress. Returns hashref of 'contact_email', 'status', and 'last_update_time' for a given domain transfer. The 'status' key is always one of the following:
pending_owner (waiting on owner confirmation)
pending_admin (waiting on opensrs staff confirmation)
pending_registry (waiting on register to complete)
completed (transfer done)
cancelled (reseller cancelled transfer in progress)
undefined (no transfer in progress)
If the domain in question has no transfer in progress - instead checks to see if the domain is capable of transfer. Returns hashref of 'transferrable' (boolean) and 'reason' (string).
$cookie = $srs->get_cookie( 'example.com ');
($cookie, $expiration_date) = $srs->get_cookie( 'example.com ');
Make sure you've set_manage_auth() before attempting any cookie required APIs.
Returns cookie on success, undefined on error. (Check error with last_response())
In array context, returns cookie and expiration date of the domain.
my $results = $srs->get_expiring_domains( 60 );
Fetch and return OpenSRS hashref of expiring domains, within
the specified timeperiod. (In days.)
Time period defaults to 30 days.
my $result = $srs->is_available( 'example.com ');
Returns true if the domain is available, false if it is already registered.
my $result = $srs->register_domain( 'example.com', $c );
Register a new domain. Default nameserver and tech info used from OpenSRS settings.
my $result = $srs->renew_domain( 'example.com', 1 );
Renew a domain for a period of time in years. 1 year is the default.
my $result = $srs->revoke_domain( 'example.com' );
Returns true if the revoke is successful, false otherwise. Returns undefined on error.
my $result = $srs->transfer_domain( 'example.com', $c );
Transfer a domain under your control. Returns true on success, false on failure, and undefined on caller error.
Examples:
my $result = $srs->make_request(
{
batch => 1,
action => 'submit',
object => 'bulk_change',
attributes => {
change_type => 'domain_lock',
change_items => [ 'example.com', 'example.net' ],
op_type => 'lock',
}
}
);
my $result = $srs->make_request(
{
action => 'lookup',
object => 'domain',
attributes => {
domain => 'example.com'
}
}
);
Returns a hashref containing parsed XML results from OpenSRS.
Example return:
{
'protocol' => 'XCP',
'object' => 'DOMAIN',
'response_text' => 'Domain taken',
'action' => 'REPLY',
'response_code' => '211',
'attributes' => {
'status' => 'taken',
'match' => {}
},
'is_success' => '1'
}
Mahlon E. Smith mahlon@martini.nu for Spime Solutions Group (www.spime.net)
Hey! The above document had some coding errors, which are explained below:
| 2022-12-11 | perl v5.36.0 |