NAME
    WebService::Amazon::Route53 - Perl interface to Amazon Route 53 API

VERSION
    Version 0.01

SYNOPSIS
    WebService::Amazon::Route53 provides an interface to Amazon Route 53 DNS
    service.

        use WebService::Amazon::Route53;

        my $r53 = WebService::Amazon::Route53->new(id => 'ROUTE53ID',
                                                   key => 'SECRETKEY');
    
        # Create a new zone
        $r53->create_hosted_zone(name => 'example.com.',
                                 caller_reference => 'example.com_migration_01');
    
        # Get zone information
        my $zone = $r53->find_hosted_zone(name => 'example.com.');
    
        # Create a new record
        $r53->change_resource_record_sets(zone_id => $zone->{id},
                                          action => 'create',
                                          name => 'www.example.com.',
                                          type => 'A',
                                          ttl => 86400,
                                          value => '12.34.56.78');

        # Modify records
        $r53->change_resource_record_sets(zone_id => $zone->{id},
            changes => [
                {
                    action => 'delete',
                    name => 'www.example.com.',
                    type => 'A',
                    ttl => 86400,
                    value => '12.34.56.78'
                },
                {
                    action => 'create',
                    name => 'www.example.com.',
                    type => 'A',
                    ttl => 86400,
                    records => [
                        '34.56.78.90',
                        '56.78.90.12'
                    ]
                }
            ]);

METHODS
    Required parameters are marked as such, other parameters are optional.

    Instance methods return "undef" on failure. More detailed error
    information can be obtained by calling "error".

  new
    Creates a new instance of WebService::Amazon::Route53.

        my $r53 = WebService::Amazon::Route53->new(id => 'ROUTE53ID',
                                                   key => 'SECRETKEY');

    Parameters:

    *   id

        (Required) AWS access key ID.

    *   key

        (Required) Secret access key.

  list_hosted_zones
    Gets a list of hosted zones.

    Called in scalar context:

        $zones = $r53->list_hosted_zones(max_items => 15);

    Called in list context:

        ($zones, $next_marker) = $r53->list_hosted_zones(marker => '456ZONEID',
                                                         max_items => 15);

    Parameters:

    *   marker

        Indicates where to begin the result set. This is the ID of the last
        hosted zone which will not be included in the results.

    *   max_items

        The maximum number of hosted zones to retrieve.

    Returns: A reference to an array of hash references, containing zone
    data. Example:

        $zones = [
            {
                'id' => '/hostedzone/123ZONEID',
                'name' => 'example.com.',
                'caller_reference' => 'ExampleZone',
                'config' => {
                    'comment' => 'This is my first hosted zone'
                }
            },
            {
                'id' => '/hostedzone/456ZONEID',
                'name' => 'example2.com.',
                'caller_reference' => 'ExampleZone2',
                'config' => {
                    'comment' => 'This is my second hosted zone'
                }
            }
        ];

    When called in list context, it also returns the next marker to pass to
    a subsequent call to "list_hosted_zones" to get the next set of results.
    If this is the last set of results, next marker will be "undef".

  get_hosted_zone
    Gets hosted zone data.

        $zone = get_hosted_zone(zone_id => '123ZONEID');

    Parameters:

    *   zone_id

        (Required) Hosted zone ID.

    Returns: A reference to a hash containing zone data. Example:

        $zone = {
            'id' => '/hostedzone/123ZONEID'
            'name' => 'example.com.',
            'caller_reference' => 'ExampleZone',
            'config' => {
                'comment' => 'This is my first hosted zone'
            }
        };

  find_hosted_zone
    Finds the first hosted zone with the given name.

        $zone = $r53->find_hosted_zone(name => 'example.com.');

    Parameters:

    *   name

        (Required) Hosted zone name.

    Returns: A reference to a hash containing zone data (see
    "get_hosted_zone"), or 0 if there is no hosted zone with the given name.

  create_hosted_zone
    Creates a new hosted zone.

        $response = $r53->create_hosted_zone(name => 'example.com.',
                                             caller_reference => 'example.com_01');

    Parameters:

    *   name

        (Required) New hosted zone name.

    *   caller_reference

        (Required) A unique string that identifies the request.

    Returns: A reference to a hash containing new zone data, change
    description, and name servers information. Example:

        $response = {
            'zone' => {
                'id' => '/hostedzone/123ZONEID'
                'name' => 'example.com.',
                'caller_reference' => 'example.com_01',
                'config' => {}
            },
            'change_info' => {
                'id' => '/change/123CHANGEID'
                'submitted_at' => '2011-08-30T23:54:53.221Z',
                'status' => 'PENDING'
            },
            'delegation_set' => {
                'name_servers' => [
                    'ns-001.awsdns-01.net',
                    'ns-002.awsdns-02.net',
                    'ns-003.awsdns-03.net',
                    'ns-004.awsdns-04.net'
                ]
            },
        };

  delete_hosted_zone
    Deletes a hosted zone.

        $change_info = $r53->delete_hosted_zone(zone_id => '123ZONEID');

    Parameters:

    *   zone_id

        (Required) Hosted zone ID.

    Returns: A reference to a hash containing change information. Example:

        $change_info = {
            'id' => '/change/123CHANGEID'
            'submitted_at' => '2011-08-31T00:04:37.456Z',
            'status' => 'PENDING'
        };

  list_resource_record_sets
    Lists resource record sets for a hosted zone.

    Called in scalar context:

        $record_sets = $r53->list_resource_record_sets(zone_id => '123ZONEID');

    Called in list context:

        ($record_sets, $next_record) = $r53->list_resource_record_sets;

    Parameters:

    *   zone_id

        (Required) Hosted zone ID.

    *   name

        The first domain name (in lexicographic order) to retrieve.

    *   type

        DNS record type of the next resource record set to retrieve.

    *   identifier

        Set identifier for the next source record set to retrieve. This is
        needed when the previous set of results has been truncated for a
        given DNS name and type.

    *   max_items

        The maximum number of records to be retrieved. The default is 100,
        and it's the maximum allowed value.

    Returns: A reference to an array of hash references, containing record
    set data. Example:

        $record_sets = [
            {
                name => 'example.com.',
                type => 'MX'
                ttl => 86400,
                records => [
                    '10 mail.example.com'
                ]
            },
            {
                name => 'example.com.',
                type => 'NS',
                ttl => 172800,
                records => [
                    'ns-001.awsdns-01.net.',
                    'ns-002.awsdns-02.net.',
                    'ns-003.awsdns-03.net.',
                    'ns-004.awsdns-04.net.'
                ]
            }
        ];

    When called in list context, it also returns a reference to a hash,
    containing information on the next record which can be passed to a
    subsequent call to "list_resource_record_sets" to get the next set of
    records (using the "name" and "type" parameters). Example:

        $next_record = {
            name => 'www.example.com.',
            type => 'A'
        };

    If this is the last set of records, next record will be "undef".

  change_resource_record_sets
    Makes changes to DNS record sets.

        $change_info = $r53->change_resource_record_sets(zone_id => '123ZONEID',
                changes => [
                    # Delete the current A record
                    {
                        action => 'delete',
                        name => 'www.example.com.',
                        type => 'A',
                        ttl => 86400,
                        value => '12.34.56.78'
                    },
                    # Create a new A record with a different value
                    {
                        action => 'create',
                        name => 'www.example.com.',
                        type => 'A',
                        ttl => 86400,
                        value => '34.56.78.90'
                    },
                    # Create two new MX records
                    {
                        action => 'create',
                        name => 'example.com.',
                        type => 'MX',
                        ttl => 86400,
                        records => [
                            '10 mail.example.com',
                            '20 mail2.example.com'
                        ]
                    }
                ]);

    If there is just one change to be made, you can use the simplified call
    syntax, and pass the change parameters immediately, instead of using the
    "changes" parameter:

        $change_info = $r53->change_resource_record_sets(zone_id => '123ZONEID',
                                                         action => 'delete',
                                                         name => 'www.example.com.',
                                                         type => 'A',
                                                         ttl => 86400,
                                                         value => '12.34.56.78');

    Parameters:

    *   zone_id

        (Required) Hosted zone ID.

    *   changes

        (Required) A reference to an array of hashes, describing the changes
        to be made. If there is just one change, it may be omitted and ...

    Change parameters:

    *   action

        The action to perform ("create" or "delete").

    *   name

        The name of the domain to perform the action on.

    *   type

        The DNS record type.

    *   ttl

        The DNS record time to live (TTL), in seconds.

    *   records

        An array of strings that represent the current or new record values.
        If there is just one value, you can use the "value" parameter
        instead.

    *   value

        Current or new DNS record value. For multiple record values, use the
        "records" parameter.

    Returns: A reference to a hash containing change information. Example:

        $change_info = {
            'id' => '/change/123CHANGEID'
            'submitted_at' => '2011-08-31T00:04:37.456Z',
            'status' => 'PENDING'
        };

  error
    Returns the last error.

        $error = $r53->error;

    Returns: A reference to a hash containing the type, code, and message of
    the last error. Example:

        $error = {
            'type' => 'Sender',
            'message' => 'FATAL problem: UnsupportedCharacter encountered at  ',
            'code' => 'InvalidDomainName'
        };

AUTHOR
    Michal Wojciechowski, "<odyniec at cpan.org>"

BUGS
    Please report any bugs or feature requests to
    "bug-webservice-amazon-route53 at rt.cpan.org", or through the web
    interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WebService-Amazon-Route5
    3>. I will be notified, and then you'll automatically be notified of
    progress on your bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc WebService::Amazon::Route53

    You can also look for information at:

    *   RT: CPAN's request tracker

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=WebService-Amazon-Route53>

    *   AnnoCPAN: Annotated CPAN documentation

        <http://annocpan.org/dist/WebService-Amazon-Route53>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/WebService-Amazon-Route53>

    *   Search CPAN

        <http://search.cpan.org/dist/WebService-Amazon-Route53/>

SEE ALSO
    *   Amazon Route 53 API Reference

        <http://docs.amazonwebservices.com/Route53/latest/APIReference/>

ACKNOWLEDGEMENTS
LICENSE AND COPYRIGHT
    Copyright 2011 Michal Wojciechowski.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.