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

cpanm WebService::DigitalOcean

perl -MCPAN -e shell
install WebService::DigitalOcean