Provided by: libweb-api-perl_2.8-1_all 
NAME
Web::API - A Simple base module to implement almost every RESTful API with just a few lines of
configuration
VERSION
version 2.8
SYNOPSIS
NOTE: as of version 2.1 "strict_ssl" is enabled by default for obvious security reasons, this may break
your current library implementation, sorry.
Implement the RESTful API of your choice in 10 minutes, roughly.
package Net::CloudProvider;
use Mouse;
with 'Web::API';
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 => [
'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(__PACKAGE__ . ' ' . $VERSION);
$self->live_url('https://ams01.cloudprovider.net/virtual_machines');
$self->content_type('application/json');
$self->extension('json');
$self->wrapper('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->new(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,
});
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
path
mandatory
default_attributes
headers
extension
content_type
incoming_content_type
outgoing_content_type
wrapper
query_keys
require_id (deprecated, use path)
pre_id_path (deprecated, use path)
post_id_path (deprecated, use path)
the request path for commands is being build as:
$base_url/$path.$extension
an example for "path":
path => 'users/:user_id/labels'
this will add "user_id" to the list of mandatory keys for this command automatically.
live_url (required)
get/set base URL to API, can include paths
test_url (optional)
get/set base URL for test system if applicable
test (optional)
get/set boolean to run against base URL from test system or live system
api_key (required in most cases)
get/set API key (also used as basic auth password)
user (optional)
get/set API username/account name
api_key_field (optional)
get/set name of the hash key that has to hold the "api_key" e.g. in POST content payloads
api_version (optional)
get/set API version to be used
default: 1
mapping (optional)
supply mapping table, hashref of format { "key" => "value", ... }
wrapper (optional)
get/set name of the key that is used to wrap all options of a command in. unfortunately some APIs
increase the depth of a hash by wrapping everything into a single key (who knows why...), which means
this:
$wa->command(%options);
turns %options into:
{ wrapper => \%options }
before encoding and sending it off.
header (optional)
get/set custom headers sent with every request
auth_type
get/set authentication type. currently supported are only 'basic', 'header', 'hash_key', 'get_params',
'oauth_header', 'oauth_params' or 'none'
default: none
auth_header (optional)
get/set the name of the header used for Authorization credentials
default: Authorization
auth_header_token_format
get/set format of the auth_header token.
default: 'Token token=%s'
default_method (optional)
get/set default HTTP method
default: GET
extension (optional)
get/set file extension, e.g. 'json'
user_agent (optional)
get/set User Agent String
default: "Web::API $VERSION"
timeout (optional)
get/set LWP::UserAgent timeout
strict_ssl (optional)
enable/disable strict SSL certificate hostname checking as a convenience alternatively you can supply
your own LWP::Useragent compatible agent for the "agent" attribute.
default: true
agent (optional)
get/set LWP::UserAgent object
retry_http_codes (optional)
get/set array of HTTP response codes that trigger a retry of the request
retry_errors (optional)
define an array reference of regexes that should trigger a retry of the request if matched against an
error found via one of the "error_keys"
retry_times (optional)
get/set number of times a request will be retried at most
default: 3
retry_delay (optional)
get/set delay to wait between retries. accepts float for millisecond support.
default: 1.0
content_type (optional)
global content type, which is used for in and out going request/response headers and to encode and decode
the payload if no other more specific content types are set, e.g. "incoming_content_type",
"outgoing_content_type" or content types set individually per command attribute.
default: 'text/plain'
incoming_content_type (optional)
default: undef
outgoing_content_type (optional)
default: undef
debug (optional)
enable/disabled debug logging
default: false
cookies (optional)
this is used to store and retrieve cookies before and after requests were made to keep authenticated
sessions alive for the time this object exists in memory you can add your own cookies to be send with
every request. See HTTP::Cookies for more information.
default: HTTP::Cookies->new()
consumer_secret (required for all oauth_* auth_types)
default: undef
access_token (required for all oauth_* auth_types)
default: undef
access_secret (required for all oauth_* auth_types)
default: undef
signature_method (required for all oauth_* auth_types)
default: undef
encoder (custom options encoding subroutine)
Receives "\%options" and "content-type" as the only 2 arguments and has to return a single scalar.
default: undef
decoder (custom response content decoding subroutine)
Receives "content" and "content-type" as the only 2 scalar arguments and has to return a single hash
reference.
default: undef
oauth_post_body (required for all oauth_* auth_types)
enable/disable adding of command options as extra parameters to the OAuth request generation and therefor
be included in the OAuth signature calculation.
default: true
error_keys
get/set list of array keys that will be search for in the decoded response data structure. the same
format as for mandatory keys is supported:
some.deeply.nested.error.message
will search for an error message at
$decoded_response->{some}->{deeply}->{nested}->{error}->{messsage}
and if the key exists and its value is defined it will be provided as "$response-"{error}> and matched
against all regexes from the `retry_errors` array ref if provided to trigger a retry on particular
errors.
INTERNAL SUBROUTINES/METHODS
nonce
generates new OAuth nonce for every request
log
decode
encode
talk
map_options
check_mandatory
key_exists
wrap
request
retry request with delay if "retry_http_codes" is set, otherwise just try once.
needs_retry
returns true if the HTTP code or error found match either "retry_http_codes" or "retry_errors"
respectively. returns false otherwise.
if "retry_errors" are defined it will try to decode the response content and store the decoded structure
internally so we don't have to decode again at the end.
needs the last response object and the 'Accept' content type header from the request for decoding.
find_error
go through "error_keys" and find a potential error message in the decoded/parsed response and return it.
format_response
build_uri
build_content_type
configure in/out content types
order of precedence: 1. per command "incoming_content_type" / "outgoing_content_type" 2. per command
general "content_type" 3. content type based on file path extension (only for incoming) 4. global
"incoming_content_type" / "outgoing_content_type" 5. global general "content_type"
DESTROY
catch DESTROY call and tear down / clean up if necessary at this point there is nothing to do though.
This prevents AUTOLOAD from logging an unknown command error message
AUTOLOAD magic
install a method for each new command and call it in an "eval {}" to catch exceptions and set an error in
a unified way.
BUGS
Please report any bugs or feature requests on GitHub's issue tracker
<https://github.com/nupfel/Web-API/issues>. Pull requests welcome.
SUPPORT
You can find documentation for this module with the perldoc(1) command. perldoc Web::API You can also look for information at: • GitHub repository <https://github.com/nupfel/Web-API> • MetaCPAN <https://metacpan.org/module/Web::API> • AnnoCPAN: Annotated CPAN documentation <http://annocpan.org/dist/Web::API> • CPAN Ratings <http://cpanratings.perl.org/d/Web::API>
SEE ALSO
HTTP::Cookies, LWP::UserAgent, Net::OAuth
AUTHOR
Tobias Kirschstein <lev@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2013 by Tobias Kirschstein.
This is free software, licensed under:
The (three-clause) BSD License