Web::API - Web::API - A Simple base module to implement almost every RESTful API with just a few lines of configuration
version 2.2
NOTE: as of version 2.1 strict_ssl is enabled by default for obvious security reasons, this may break your current library implementation, sorry.
strict_ssl
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->base_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(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, });
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 require_id (depricated, use path) pre_id_path (depricated, use path) post_id_path (depriated, use path)
the request path for commands is being build as:
$base_url/$path.$extension
an example for path:
path
path => 'users/:user_id/labels'
this will add user_id to the list of mandatory keys for this command automatically.
user_id
get/set base URL to API, can include paths
get/set API key (also used as basic auth password)
get/set API username/account name
get/set name of the hash key that has to hold the api_key e.g. in POST content payloads
api_key
supply mapping table, hashref of format { "key" => "value", ... }
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:
%options
{ wrapper => \%options }
before encoding and sending it off.
get/set custom headers sent with every request
get/set authentication type. currently supported are only 'basic', 'hash_key', 'get_params', 'oauth_header', 'oauth_params' or 'none'
default: none
get/set default HTTP method
default: GET
get/set file extension, e.g. '.json'
get/set User Agent String
default: "Web::API $VERSION"
get/set LWP::UserAgent timeout
enable/disable strict SSL certificate hostname checking as a convenience alternatively you can supply your own LWP::Useragent compatible agent for the agent attribute.
agent
default: true
get/set LWP::UserAgent object
get/set array of HTTP response codes that trigger a retry of the request
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
error_keys
get/set amount of times a request will be retried at most
default: 3
get/set delay to wait between retries. accepts float for millisecond support.
default: 1.0
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.
incoming_content_type
outgoing_content_type
default: 'text/plain'
default: undef
enable/disabled debug logging
default: false
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.
default: HTTP::Cookies->new
Receives \%options and content-type as the only 2 arguments and has to return a single scalar.
\%options
content-type
Receives content and content-type as the only 2 scalar arguments and has to return a single hash reference.
content
enable/disable adding of command options as extra parameters to the OAuth request generation and therefor be included in the OAuth signature calculation.
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.
$response-
generates new OAuth nonce for every request
retry request with delay if retry_http_codes is set, otherwise just try once.
retry_http_codes
returns true if the HTTP code or error found match either retry_http_codes or retry_errors respectively. returns false otherwise.
retry_errors
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.
go through error_keys and find a potential error message in the decoded/parsed response and return it.
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
content_type
install a method for each new command and call it in an eval {} to catch die()s and set an error in a unified way.
Please report any bugs or feature requests on GitHub's issue tracker https://github.com/nupfel/Web-API/issues. Pull requests welcome.
You can find documentation for this module with the perldoc 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
Tobias Kirschstein <lev@cpan.org>
This software is Copyright (c) 2013 by Tobias Kirschstein.
This is free software, licensed under:
The (three-clause) BSD License
To install Web::API, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Web::API
CPAN shell
perl -MCPAN -e shell install Web::API
For more information on module installation, please visit the detailed CPAN module installation guide.