File Coverage

blib/lib/WebService/DNSwatch.pm
Criterion Covered Total %
statement 15 81 18.5
branch 0 28 0.0
condition n/a
subroutine 5 11 45.4
pod 5 5 100.0
total 25 125 20.0


line stmt bran cond sub pod time code
1             package WebService::DNSwatch;
2              
3 1     1   29786 use warnings;
  1         3  
  1         37  
4 1     1   5 use strict;
  1         2  
  1         35  
5              
6 1     1   6 use Carp;
  1         6  
  1         93  
7 1     1   4880 use LWP::UserAgent;
  1         94622  
  1         36  
8 1     1   10 use URI::Escape;
  1         1  
  1         975  
9              
10             =head1 NAME
11              
12             WebService::DNSwatch - Perl interface to the DNSwatch API
13              
14             =head1 VERSION
15              
16             Version 0.02
17              
18             =cut
19              
20             our $VERSION = '0.02';
21              
22              
23             =head1 SYNOPSIS
24              
25             WebService::DNSwatch provides an interface to the DNSwatch API, allowing
26             for control of domains and records hosted at DNSwatch.
27              
28             use WebService::DNSwatch;
29              
30             # Create a new instance of WebService::DNSwatch
31             my $editdns = WebService::DNSwatch->new(email => 'your@email.address',
32             apihash => 'your_API_hash');
33              
34             # Add a new domain
35             $dnswatch->add_domain(domain => 'example.com');
36              
37             # Add a type A record
38             $dnswatch->add_record(domain => 'example.com',
39             record => 'www.example.com',
40             type => 'A',
41             data => '12.34.56.78');
42              
43             # Delete a record
44             $dnswatch->delete_record(domain => 'example.com',
45             record => 'www.example.com',
46             type => 'A');
47              
48             # Delete a domain
49             $dnswatch->delete_domain(domain => 'example.com');
50              
51             ...
52              
53             =head1 METHODS
54              
55             =head2 new
56              
57             Creates a new instance of WebService::DNSwatch.
58              
59             my $dnswatch = WebService::DNSwatch->new(email => 'your@email.address',
60             apihash => 'your_API_hash');
61              
62             Parameters:
63              
64             =over 4
65              
66             =item * email
67              
68             B<(Required)> E-mail address registered at DNSwatch.net.
69              
70             =item * apihash
71              
72             B<(Required)> API hash generated for the DNSwatch account.
73              
74             =item * domain
75              
76             I<(Optional)> Domain name. If specified in the constructor call, it can
77             be ommitted in further calls to L<"add_record"> and L<"delete_record">.
78              
79             =back
80              
81             =cut
82              
83             sub new {
84 0     0 1   my $class = shift;
85 0           my %args = @_;
86              
87 0           my $self = {};
88 0           bless($self, $class);
89              
90 0 0         if (!defined $args{'email'}) {
91 0           carp "Required parameter 'email' is not defined";
92             }
93              
94 0 0         if (!defined $args{'apihash'}) {
95 0           carp "Required parameter 'apihash' is not defined";
96             }
97              
98 0           $self->{'email'} = $args{'email'};
99 0           $self->{'apihash'} = $args{'apihash'};
100 0           $self->{'domain'} = $args{'domain'};
101              
102 0           $self->{'ua'} = LWP::UserAgent->new;
103 0           $self->{'ua'}->agent("WebService::DNSwatch/$VERSION (Perl)");
104              
105 0           return $self;
106             }
107              
108             # Send a DNSwatch API request
109              
110             sub _api_request {
111 0     0     my $self = shift;
112 0           my %args = (
113             'email' => $self->{'email'},
114             'apihash' => $self->{'apihash'},
115             'domain' => $self->{'domain'},
116             @_
117             );
118              
119 0 0         if (!defined $args{'email'}) {
120 0           carp "Required parameter 'email' is not defined";
121             }
122              
123 0 0         if (!defined $args{'apihash'}) {
124 0           carp "Required parameter 'apihash' is not defined";
125             }
126              
127 0 0         if (!defined $args{'domain'}) {
128 0           carp "Required parameter 'domain' is not defined";
129             }
130              
131 0           my $url = 'https://dnswatch.net/api/api';
132 0           my $prefix = '?';
133              
134 0           for my $arg (keys %args) {
135 0           $url .= $prefix . $arg . '=' . uri_escape($args{$arg});
136 0           $prefix = '&';
137             }
138              
139 0           my $request = HTTP::Request->new(GET => $url);
140              
141             # Send the request and get the response
142 0           my $response = $self->{'ua'}->request($request);
143              
144             # Received an HTTP error code
145 0 0         if (!$response->is_success) {
146 0           carp "Request failed (Server response: \"" .
147             $response->status_line . "\")";
148 0           return undef;
149             }
150              
151             # Successful DNSwatch API responses start with "200:", if it's missing then
152             # we have an error
153 0 0         if ($response->content !~ /^200:/) {
154 0           (my $error = $response->content) =~ s/\n$//;
155 0           carp "Operation failed (API error message: \"" .
156             $error . "\")";
157 0           return undef;
158             }
159             }
160              
161             =head2 add_domain
162              
163             Adds a new domain.
164              
165             $dnswatch->add_domain(domain => 'example.com');
166              
167             Parameters:
168              
169             =over 4
170              
171             =item * domain
172              
173             B<(Required)> Domain name.
174              
175             =item * default_ip
176              
177             I<(Optional)> Default IP address that the domain's root and www records will
178             point to.
179              
180             =item * master_ns
181              
182             I<(Optional)> The IP address or hostname of a master nameserver (for
183             backup/slave domains).
184              
185             =back
186              
187             =cut
188              
189             sub add_domain {
190 0     0 1   my $self = shift;
191 0           my %args = @_;
192              
193             # Translate parameter names (DNSwatch uses camelCase)
194 0 0         $args{'defaultIP'} = $args{'default_ip'} if defined $args{'default_ip'};
195 0 0         $args{'masterNS'} = $args{'master_ns'} if defined $args{'master_ns'};
196              
197             # Make original parameters undefined
198 0           $args{'default_ip'} = undef;
199 0           $args{'master_ns'} = undef;
200              
201 0           $args{'addDomain'} = '1';
202              
203 0           return $self->_api_request(%args);
204             }
205              
206             =head2 delete_domain
207              
208             Deletes a domain.
209              
210             $dnswatch->delete_domain(domain => 'example.com');
211              
212             Parameters:
213              
214             =over 4
215              
216             =item * domain
217              
218             B<(Required)> Domain name.
219              
220             =back
221              
222             =cut
223              
224             sub delete_domain {
225 0     0 1   my $self = shift;
226 0           my %args = @_;
227              
228 0           $args{'deleteDomain'} = '1';
229              
230 0           return $self->_api_request(%args);
231             }
232              
233             =head2 add_record
234              
235             Adds a new record.
236              
237             $dnswatch->add_record(domain => 'example.com',
238             record => 'www.example.com',
239             type => 'A',
240             data => '12.34.56.78')
241              
242             Parameters:
243              
244             =over 4
245              
246             =item * domain
247              
248             B<(Required)> Domain name. Can be ommitted if set with L<"new">.
249              
250             =item * record
251              
252             B<(Required)> Record name.
253              
254             =item * type
255              
256             B<(Required)> Record type (e.g., "A", "MX", "CNAME", etc.).
257              
258             =item * data
259              
260             B<(Required)> Record data (e.g., IP address for a type A record).
261              
262             =item * ttl
263              
264             I<(Optional)> TTL (time to live) value for the record.
265              
266             =item * aux
267              
268             I<(Optional)> AUX value for the record (mostly used with MX records).
269              
270             =back
271              
272             =cut
273              
274             sub add_record {
275 0     0 1   my $self = shift;
276 0           my %args = @_;
277              
278 0 0         if (!defined $args{'record'}) {
279 0           carp "Required parameter 'record' is not defined";
280             }
281              
282 0 0         if (!defined $args{'type'}) {
283 0           carp "Required parameter 'type' is not defined";
284             }
285              
286 0 0         if (!defined $args{'data'}) {
287 0           carp "Required parameter 'data' is not defined";
288             }
289              
290 0           $args{'addRecord'} = '1';
291              
292 0           return $self->_api_request(%args);
293             }
294              
295             =head2 delete_record
296              
297             Deletes a record.
298              
299             $dnswatch->delete_record(domain => 'example.com',
300             record => 'mail.example.com',
301             type => 'MX');
302              
303             Parameters:
304              
305             =over 4
306              
307             =item * domain
308              
309             B<(Required)> Domain name. Can be ommitted if set with L<"new">.
310              
311             =item * record
312              
313             B<(Required)> Record name.
314              
315             =item * type
316              
317             B<(Required)> Record type.
318              
319             =back
320              
321             =cut
322              
323             sub delete_record {
324 0     0 1   my $self = shift;
325 0           my %args = @_;
326              
327 0 0         if (!defined $args{'record'}) {
328 0           carp "Required parameter 'record' is not defined";
329             }
330              
331 0 0         if (!defined $args{'type'}) {
332 0           carp "Required parameter 'type' is not defined";
333             }
334              
335 0           $args{'deleteRecord'} = '1';
336              
337 0           return $self->_api_request(%args);
338             }
339              
340             =head1 AUTHOR
341              
342             C Hutchinson, C<< >>
343              
344             =head1 BUGS
345              
346             Please report any bugs or feature requests to C, or through
347             the web interface at L. I will be notified, and then you'll
348             automatically be notified of progress on your bug as I make changes.
349              
350              
351              
352              
353             =head1 SUPPORT
354              
355             You can find documentation for this module with the perldoc command.
356              
357             perldoc WebService::DNSwatch
358              
359              
360             You can also look for information at:
361              
362             =over 4
363              
364             =item * RT: CPAN's request tracker
365              
366             L
367              
368             =item * AnnoCPAN: Annotated CPAN documentation
369              
370             L
371              
372             =item * CPAN Ratings
373              
374             L
375              
376             =item * Search CPAN
377              
378             L
379              
380             =back
381              
382              
383             =head1 COPYRIGHT & LICENSE
384              
385             Copyright 1985-2013 C Hutchinson, all rights reserved.
386              
387             This program is free software; you can redistribute it and/or modify it
388             under the same terms as Perl itself.
389              
390              
391             =cut
392              
393             1; # PolyGraph