/ 
REST-Client-Simple-0.3
/ REST::Client::Simple

NAME

REST::Client::Simple - A Simple base module to implement almost every RESTful API with just a few lines of configuration

VERSION

Version 0.3.3

SYNOPSIS

Implement the RESTful API of your choice in 10 minutes, roughly.

package Net::CloudProvider;

use Any::Moose;
use Data::Dumper;
with 'REST::Client::Simple';

our $VERSION = "0.1";

has 'commands' => (
    is      => 'rw',
    default => sub {
        {
            list_nodes => { method => 'GET' },
            node_info  => { method => 'GET', require_id => 1 },
            create_node => {
                method             => 'POST',
                default_attributes => {
                    allowed_hot_migrate            => 1,
                    required_virtual_machine_build => 1,
                    cpu_shares                     => 5,
                    required_ip_address_assignment => 1,
                    primary_network_id             => 1,
                    required_automatic_backup      => 0,
                    swap_disk_size                 => 1,
                },
                mandatory_attributes => [
                    'label',
                    'hostname',
                    'template_id',
                    'cpus',
                    'memory',
                    'primary_disk_size',
                    'required_virtual_machine_build',
                    'cpu_shares',
                    'primary_network_id',
                    'required_ip_address_assignment',
                    'required_automatic_backup',
                    'swap_disk_size',
                ]
            },
            update_node => { method => 'PUT',    require_id => 1 },
            delete_node => { method => 'DELETE', require_id => 1 },
            start_node  => {
                method       => 'POST',
                require_id   => 1,
                post_id_path => 'startup',
            },
            stop_node => {
                method       => 'POST',
                require_id   => 1,
                post_id_path => 'shutdown',
            },
            suspend_node => {
                method       => 'POST',
                require_id   => 1,
                post_id_path => 'suspend',
            },
        };
    },
);

sub commands {
    my ($self) = @_;
    return $self->commands;
}

sub BUILD {
    my ($self) = @_;

    $self->user_agent("Net::CloudProvider $VERSION");
    $self->base_url('https://ams01.cloudprovider.net/virtual_machines');
    $self->content_type('application/json');
    $self->extension('json');
    $self->wrapper_key('virtual_machine');
    $self->mapping({
            os        => 'template_id',
            debian    => 1,
            id        => 'label',
            disk_size => 'primary_disk_size',
    });

    return $self;
}

1;

later use as:

use Net::CloudProvider;

my $nc = Net::CloudProvider(user => 'foobar', api_key => 'secret');
my $response = $nc->create_node({
    id                             => 'funnybox',
    hostname                       => 'node.funnybox.com',
    os                             => 'debian',
    cpus                           => 2,
    memory                         => 256,
    disk_size                      => 5,
    allowed_hot_migrate            => 1,
    required_virtual_machine_build => 1,
    cpu_shares                     => 5,
    required_ip_address_assignment => 1,
});
print Dumper($response);

ATTRIBUTES

commands

most important configuration part of the module which has to be provided by the module you are writing.

the following keys are valid/possible:

method
require_id
path
pre_id_path
post_id_path
wrapper_key
default_attributes
mandatory_attributes
extension
content_type
incoming_content_type
outgoing_content_type

the request path for non require_id commands is being build as:

$base_url/$path.$extension

accordingly requests with require_id:

$base_url/$pre_id_path/$id/$post_id_path.$extension

whereas $id can be any arbitrary object like a domain, that the API in question does operations on.

base_url (required)

get/set base URL to API, can include paths

user (required)

get/set username/account name

api_key (required)

get/set api_key

mapping (optional)

supply mapping table, hashref of format { key => value }

default: undef

wrapper_key (optional)

header (optional)

get/set custom headers sent with each request

get/set authentication type. currently supported are only 'basic' or none

default: basic

extension (optional)

get/set file extension, e.g. '.json'

user_agent (optional)

get/set User Agent String

default: "REST::Client::Simple $VERSION"

timeout (optional)

get/set LWP::UserAgent timeout

agent (optional)

get/set REST::Client object

content_type (optional)

default: 'text/plain'

incoming_content_type (optional)

default: undef

outgoing_content_type (optional)

default: undef

debug (optional)

default: 0

INTERNAL SUBROUTINES/METHODS

decode

encode

talk

map_options

AUTOLOAD magic

AUTHOR

Tobias Kirschstein, <mail at lev.geek.nz>

BUGS

Please report any bugs or feature requests to bug-rest-client-simple at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=REST-Client-Simple. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

TODO

  • add OAuth athentication possibility

SUPPORT

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

perldoc REST::Client::Simple

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2012 Tobias Kirschstein.

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.