The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WebService-DigitalOcean-0.026
River stage zero No dependents
2 ++
/ WebService::DigitalOcean

NAME

WebService::DigitalOcean - Access the DigitalOcean RESTful API (v2)

VERSION

version 0.026

SYNOPSIS

    use WebService::DigitalOcean;

    my $do = WebService::DigitalOcean->new({ token => $TOKEN });

    ###
    ## Upload your public ssh key
    ###

    open my $fh, '<', $ENV{HOME} . '/.ssh/id_rsa.pub';
    my $key = $do->key_create({
        name       => 'Andre Walker',
        public_key => do { local $/ = <$fh> },
    });
    close $fh;

    ###
    ## Select a random available region to create a droplet
    ###

    my @regions = grep { $_->{available} } @{ $do->region_list->{content} };
    my $random_region = $regions[rand @regions];

    ###
    ## Create droplets!
    ###

    my $droplet1_res = $do->droplet_create({
        name               => 'server1.example.com',
        region             => $random_region->{slug},
        size               => '1gb',
        image              => 'ubuntu-14-04-x64',
        ssh_keys           => [ $key->{content}{fingerprint} ],
    });

    die "Could not create droplet 1" unless $droplet1_res->{is_success};

    my $droplet2_res = $do->droplet_create({
        name               => 'server2.example.com',
        region             => $random_region->{slug},
        size               => '1gb',
        image              => 'ubuntu-14-04-x64',
        ssh_keys           => [ $key->{content}{fingerprint} ],
    });

    die "Could not create droplet 2" unless $droplet2_res->{is_success};

    ###
    ## Create domains
    ###

    my $subdomain1_res = $do->domain_record_create({
        domain => 'example.com',
        type   => 'A',
        name   => 'server1',
        data   => $droplet1_res->{content}{networks}{v4}{ip_address},
    });

    die "Could not create subdomain server1" unless $subdomain1_res->{is_success};

    my $subdomain2_res = $do->domain_create({
        domain => 'example.com',
        type   => 'A',
        name   => 'server2',
        data   => $droplet2_res->{content}{networks}{v4}{ip_address},
    });

    die "Could not create subdomain server2" unless $subdomain2_res->{is_success};

DESCRIPTION

This module implements DigitalOceans new RESTful API.

ATTRIBUTES

api_base_url

A string prepended to all API endpoints. By default, it's https://api.digitalocean.com/v2. This can be adjusted to facilitate tests.

token

The authorization token. It can be retrieved by logging into one's DigitalOcean account, and generating a personal token here: https://cloud.digitalocean.com/settings/applications.

METHODS

domain_create

    my $res = $do->domain_create({
        name       => 'example.com',
        ip_address => '12.34.56.78',
    });

Arguments:

Str $args{name}

The domain name.

Str $args{ip_address}

The IP address the domain will point to.

Creates a new top level domain.

More info: https://developers.digitalocean.com/documentation/v2/#create-a-new-domain.

domain_delete

    $do->domain_delete('example.com');

Arguments:

Str $domain

The domain name.

Deletes the specified domain.

More info: https://developers.digitalocean.com/documentation/v2/#delete-a-domain.

domain_get

    my $response = $do->domain_get('example.com');

Arguments:

Str $domain

The domain name.

Retrieves the specified domain.

More info: https://developers.digitalocean.com/documentation/v2/#retrieve-an-existing-domain.

domain_list

    my $response = $do->domain_list();

    for (@{ $response->{content} }) {
        say $_->{id};
    }

Lists all domains for this account.

More info: https://developers.digitalocean.com/documentation/v2/#list-all-domains.

domain_record_create

    my $response = $do->domain_record_create({
        domain => 'example.com',
        type   => 'A',
        name   => 'www2',
        data   => '12.34.56.78',
    });

    my $id = $response->{content}{id};

Arguments:

Str $args{domain}

The domain under which the record will be created.

Str $args{type}

The type of the record (eg MX, CNAME, A, etc).

Str $args{name} (optional)

The name of the record.

Str $args{data} (optional)

The data (such as the IP address) of the record.

Int $args{priority} (optional)

Priority, for MX or SRV records.

Int $args{port} (optional)

The port, for SRV records.

Int $args{weight} (optional)

The weight, for SRV records.

Creates a new record for a domain.

More info: https://developers.digitalocean.com/documentation/v2/#create-a-new-domain-record.

domain_record_delete

    $do->domain_record_delete({
        domain => 'example.com',
        id     => 1215,
    });

Arguments:

Str $args{domain}

The domain to which the record belongs.

Int $args{id}

The id of the record.

Deletes the specified record.

More info: https://developers.digitalocean.com/documentation/v2/#delete-a-domain-record.

domain_record_get

    my $response = $do->domain_record_get({
        domain => 'example.com',
        id     => 1215,
    });

    my $ip = $response->{content}{data};

Arguments:

Str $args{domain}

The domain to which the record belongs.

Int $args{id}

The id of the record.

Retrieves details about a particular record, identified by id.

More info: https://developers.digitalocean.com/documentation/v2/#retrieve-an-existing-domain-record.

domain_record_list

    my $response = $do->domain_record_list('example.com');

    for (@{ $response->{content} }) {
        print "$_->{name} => $_->{data}\n";
    }

Arguments:

Str $domain

The domain to which the records belong.

Retrieves all the records for a particular domain.

More info: https://developers.digitalocean.com/documentation/v2/#list-all-domain-records.

droplet_create

    $do->droplet_create(
        name               => "My-Droplet",
        region             => "nyc1",
        size               => "512mb",
        image              => 449676389,
        ssh_keys           => [ 52341234, 215124, 64325534 ],
        backups            => 0,
        ipv6               => 1,
        private_networking => 0,
    );

Arguments:

Str $args{name}
Str $args{region}
Str $args{size}
Str $args{image}
Str $args{user_data} (optional)
ArrayRef $args{ssh_keys} (optional)
Bool $args{backups} (optional)
Bool $args{ipv6} (optional)
Bool $args{private_networking} (optional)

Creates a new droplet.

More info: https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet.

droplet_delete

    $do->droplet_delete(1250928);

Arguments:

Int $id

Deletes the specified droplet.

More info: https://developers.digitalocean.com/documentation/v2/#delete-a-droplet.

droplet_get

    my $response = $do->droplet_get(15314123);

Arguments:

Int $id

Retrieves the specified droplet.

More info: https://developers.digitalocean.com/documentation/v2/#retrieve-an-existing-droplet-by-id.

droplet_list

    my $response = $do->droplet_list();

    for (@{ $response->{content} }) {
        print $_->{id};
    }

Lists all droplets for this account.

More info: https://developers.digitalocean.com/documentation/v2/#list-all-droplets.

droplet_resize

    $do->droplet_resize({
        droplet => 123456,
        disk    => 1,
        size    => '1gb',
    });

Arguments:

Int $args{droplet}
Bool $args{disk}
Str $args{size}

Resizes a droplet.

More info: https://developers.digitalocean.com/documentation/v2/#resize-a-droplet.

droplet_change_kernel

    $do->droplet_change_kernel({
        droplet => 123456,
        kernel  => 654321,
    });

Arguments:

Int $args{droplet}
Int $args{kernel}

Changes the kernel of a droplet.

More info: https://developers.digitalocean.com/documentation/v2/#change-the-kernel.

droplet_rebuild

    $do->droplet_rebuild({
        droplet => 123456,
        image   => 654321,
    });

Arguments:

Int $args{droplet}
Str $args{image}

Rebuilds a droplet.

More info: https://developers.digitalocean.com/documentation/v2/#rebuild-a-droplet.

droplet_restore

    $do->droplet_rebuild({
        droplet => 123456,
        image   => 654321,
    });

Arguments:

Int $args{droplet}
Str $args{image}

Restores a droplet to an image backup.

More info: https://developers.digitalocean.com/documentation/v2/#restore-a-droplet.

droplet_rename

    $do->droplet_rename({
        droplet => 123456,
        name    => 'new-name',
    });

Arguments:

Int $args{droplet}
Str $args{name}

Renames a droplet, thus setting the reverse DNS.

More info: https://developers.digitalocean.com/documentation/v2/#rename-a-droplet.

droplet_snapshot

    $do->droplet_rebuild({
        droplet => 123456,
        name    => 'snapshot-name',
    });

Arguments:

Int $args{droplet}
Str $args{name}

Saves a snapshopt of the droplet.

More info: https://developers.digitalocean.com/documentation/v2/#rebuild-a-droplet.

droplet_reboot

    $do->droplet_reboot(123456);

Arguments:

Int $droplet_id

Reboots droplet.

More info: https://developers.digitalocean.com/documentation/v2/#reboot-a-droplet.

droplet_power_cycle

    $do->droplet_power_cycle(123456);

Arguments:

Int $droplet_id

Power cycles droplet.

More info: https://developers.digitalocean.com/documentation/v2/#power-cycle-a-droplet.

droplet_power_on

    $do->droplet_power_on(123456);

Arguments:

Int $droplet_id

Powers on droplet.

More info: https://developers.digitalocean.com/documentation/v2/#power-on-a-droplet.

droplet_power_off

    $do->droplet_power_off(123456);

Arguments:

Int $droplet_id

Powers off droplet.

More info: https://developers.digitalocean.com/documentation/v2/#power-off-a-droplet.

droplet_password_reset

    $do->droplet_password_reset(123456);

Arguments:

Int $droplet_id

Resets the root password of the droplet.

More info: https://developers.digitalocean.com/documentation/v2/#password-reset-a-droplet.

droplet_shutdown

    $do->droplet_shutdown(123456);

Arguments:

Int $droplet_id

Shuts down a droplet

More info: https://developers.digitalocean.com/documentation/v2/#shutdown-a-droplet.

droplet_enable_ipv6

    $do->droplet_enable_ipv6(123456);

Arguments:

Int $droplet_id

Enables IPv6 in a droplet.

More info: https://developers.digitalocean.com/documentation/v2/#enable-ipv6.

droplet_enable_private_networking

    $do->droplet_enable_private_networking(123456);

Arguments:

Int $droplet_id

Enables private networking for a droplet.

More info: https://developers.digitalocean.com/documentation/v2/#enable-private-networking.

droplet_disable_backups

    $do->droplet_disable_backups(123456);

Arguments:

Int $droplet_id

Disables backups for the droplet.

More info: https://developers.digitalocean.com/documentation/v2/#disable-backups.

droplet_action_get

    $do->droplet_action_get({
        droplet => 123456,
        action  => 53,
    });

Arguments:

Int $args{droplet}
Int $args{action}

Retrieve details from a specific action.

More info: https://developers.digitalocean.com/documentation/v2/#retrieve-a-droplet-action.

key_create

    my $response = $do->key_create({
        name       => 'my public key',
        public_key => <$public_key_fh>,
    });

Arguments:

Str $args{name}
Str $args{public_key}

Creates a new ssh key for this account.

More info: https://developers.digitalocean.com/documentation/v2/#create-a-new-key.

key_delete

    $do->key_delete({ id => 146432 });

Arguments:

Int $args{id} OR
Str $args{fingerprint}

Deletes the specified ssh key.

More info: https://developers.digitalocean.com/documentation/v2/#destroy-a-key.

key_get

    my $response = $do->key_get({ id => 1215 });

Arguments:

Int $args{id} OR
Str $args{fingerprint}

Retrieves details about a particular ssh key, identified by id or fingerprint (pick one).

More info: https://developers.digitalocean.com/documentation/v2/#retrieve-an-existing-key.

key_list

Retrieves all the keys for this account.

More info: https://developers.digitalocean.com/documentation/v2/#list-all-keys.

region_list

    my $regions = $do->region_list();

    for my $r (@{ $regions->{content} }) {
        if ($r->{available}) {
            say "$r->{name} is available";
        }
    }

Retrieves all the regions available in Digital Ocean.

More info: https://developers.digitalocean.com/documentation/v2/#list-all-regions.

size_list

Retrieves all the sizes available in Digital Ocean.

    my $sizes = $do->size_list();

    for my $s (@{ $sizes->{content} }) {
        say "Size $s->{slug} costs $s->{price_hourly} per hour.";
    }

More info: https://developers.digitalocean.com/documentation/v2/#list-all-sizes.

image_list

Retrieves all the images available in Digital Ocean.

    my $images = $do->image_list();

    for my $i (@{ $images->{content} }) {
        say join "\t", $i->{distribution}, $i->{id}, $i->{name};
    }

More info: https://developers.digitalocean.com/documentation/v2/#list-all-images.

SEE ALSO

DigitalOcean

First DigitalOcean module, uses v1 API. It has a more OO approach than this module, and might have a more stable interface at the moment.

https://developers.digitalocean.com/documentation/v2/

Documentation for API v2, in DigitalOcean's website.

AUTHOR

André Walker <andre@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2015 by André Walker.

This is free software, licensed under:

  The GNU General Public License, Version 2, June 1991