view release on metacpan or  search on metacpan

lib/Akamai/Open/DiagnosticTools.pm  view on Meta::CPAN

=head1 NAME

Akamai::Open::DiagnosticTools - The Akamai Open DiagnosticTools API Perl client

=head1 VERSION

version 0.02

=head1 SYNOPSIS

 use Akamai::Open::Client;
 use Akamai::Open::DiagnosticTools;

 my $client = Akamai::Open::Client->new();
 $client->access_token('foobar');
 $client->client_token('barfoo');
 $client->client_secret('Zm9vYmFyYmFyZm9v');

 my $diag = Akamai::Open::DiagnosticTools->new(client => $client);
 $diag->baseurl('http://mybaseurl.luna.akamaiapis.net');
 my $loc  = $diag->locations();
 my $dig  = $diag->dig({hostname => 'cpan.org', queryType => 'A', location => 'Frankfurt, Germany'});
 my $mtr  = $diag->mtr({destinationDomain => 'cpan.org', sourceIp => '23.62.61.24'});

=head1 ABOUT

I<Akamai::Open::DiagnosticTools> provides an API client for the 
Akamai Open DiagnosticTools API which is described L<here|https://developer.akamai.com/api/luna/diagnostic-tools/reference.html>.

=head1 USAGE

All API calls for the DiagnosticTools API are described and explained
at the L<Akamai Open DiagnosticTools API Portal|https://developer.akamai.com/api/luna/diagnostic-tools/reference.html>.

=head2 Akamai::Open::DiagnosticTools->new(client => $client)

For every I<Akamai::Open> API call you'll need some client credentials.
These are provided by the L<Akamai::Open:Client|http://search.cpan.org/perldoc?Akamai::Open::Client> 
module and can reviewed at the LUNA control center.

A succesfull call to I<new()> will return a I<Moose> powered 
I<Akamai::Open::DiagnosticTools> object.

=head2 $diag->baseurl($baseurl)

To successfully access an I<Akamai Open API> you'll need a baseurl, 
which is provided by the I<LUNA control center Manage API Portal> 
and is uniq to every configured API user and API itself.

I<baseurl()> is a I<Moose> powered getter/setter method, to set 
and receive the object's assigned baseurl.

=head2 $diag->locations()

To initiate diagnostinc actions inside the Akamai network, you'll
need the information about the locations from which diagnostic 
actions are available.

I<locations()> provides the informations. On success it returns a 
Perl-style array reference. On error it returns I<undef> and sets 
the I<last_error()> appropriate.

=head2 $diag->mtr($hash_ref)

I<mtr()> returns a network trace like the well know I<mtr> Unix command.

I<mtr()> accepts the following parameters in $hash_ref as a Perl-style
hash reference:

=over 4

=item * destinationDomain

The domain name you want to get information about. Example: I<cpan.org>.
This parameter is mandatory.

=item * location

Location of a Akamai Server you want to run mtr from. You can find 
servers using the I<locations()> call. This paramter is optional. 
Either location or sourceIp has to be passed to I<mtr()>

=item * sourceIp

A Akamai Server IP you want to run mtr from. This paramter is optional. 
Either location or sourceIp has to be passed to I<mtr()>

=back

On success it returns a Perl-style hash reference. On error it returns 
I<undef> and sets the I<last_error()> appropriate.

The hash reference has the following format:

  {
     'source' => ...,
     'packetLoss' => '...',
     'destination' => '...',
     'errorString' => ...,
     'analysis' => '...',
     'host' => '...',
     'avgLatency' => '...',
     'hops' => [
                 {
                   'num' => '...',
                   'avg' => '...',
                   'last' => '...',
                   'stDev' => '...',
                   'host' => '...',
                   'worst' => '...',
                   'loss' => '...',
                   'sent' => '...',
                   'best' => '...'
                 }
               ]
  }

=head2 $diag->dig($hash_ref)

I<dig()> returns dns information like the well know I<dig> Unix command.

I<dig()> accepts the following parameters in $hash_ref as a Perl-style
hash reference:

=over 4

=item * hostname

The hostname you want to get information about. Example: I<cpan.org>.
This parameter is mandatory.

=item * queryType

The query type for the dig command call, valid types are A, AAAA, 
PTR, SOA, MX and CNAME. This parameter is mandatory.

=item * location

Location of Akamai Server you want to run dig from. You can find 
servers using the I<locations()> call. This paramter is optional. 
Either location or sourceIp has to be passed to I<dig()>

=item * sourceIp

A Akamai Server IP you want to run dig from. This paramter is optional. 
Either location or sourceIp has to be passed to I<dig()>

=back

On success it returns a Perl-style hash reference. On error it returns 
I<undef> and sets the I<last_error()> appropriate.

The hash reference has the following format:

  {
      'authoritySection' => [
                             {
                                'recordType' => '...',
                                'domain' => '...',
                                'value' => '...',
                                'ttl' => '...',
                                'preferenceValues' => ...,
                                'recordClass' => '...'
                              }
                            ],
      'answerSection' => [
                          {
                             'recordType' => '...',
                             'domain' => '...',
                             'value' => '...',
                             'ttl' => '...',
                             'preferenceValues' => ...,
                             'recordClass' => '...'
                           }
                         ],
      'errorString' => ...,
      'queryType' => '...',
      'hostname' => '...',
      'result' => '...'
  }

=head2 $diag->last_error()

Just returns the last occured error.

=head1 AUTHOR

Martin Probst <internet+cpan@megamaddin.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Martin Probst.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut