package Net::HTTP::API;
# ABSTRACT: Easily create client for net API
use Moose;
use Moose::Exporter;
use Moose::Util::MetaRole;
our $VERSION = '0.11';
Moose::Exporter->setup_import_methods(
with_meta => [qw/net_api_method net_api_declare/],
also => [qw/Moose/]
);
sub net_api_method {
my $meta = shift;
my $name = shift;
$meta->add_net_api_method($name, @_);
}
sub net_api_declare {
my $meta = shift;
my $name = shift;
$meta->add_net_api_declare($name, @_);
}
sub init_meta {
my ($class, %options) = @_;
my $for = $options{for_class};
Moose->init_meta(%options);
my $meta = Moose::Util::MetaRole::apply_metaroles(
for => $for,
class_metaroles => {
class => ['Net::HTTP::API::Meta::Class'],
},
);
Moose::Util::MetaRole::apply_base_class_roles(
for => $for,
roles => [
qw/
Net::HTTP::API::Role::UserAgent
Net::HTTP::API::Role::Format
Net::HTTP::API::Role::Authentication
Net::HTTP::API::Role::Serialization
Net::HTTP::API::Role::Request
/
],
);
$meta;
}
1;
=head1 SYNOPSIS
package My::Net::API;
use Net::HTTP::API;
# we declare an API, the base_url is http://exemple.com/api
# the format is json and it will be append to the query
# You can set api_base_url later, calling $obj->api_base_url('http://..')
net_api_declare my_api => (
api_base_url => 'http://exemple.com/api',
api_format => 'json',
api_format_mode => 'append',
);
# declaring a users method
# calling $obj->users will call http://exemple.com/api/users/france
net_api_method users => (
description => 'this get a list of users',
method => 'GET',
path => '/users/:country',
params => [qw/country/],
);
# you can create your own useragent (it must be a LWP::UserAgent object)
net_api_declare my_api => (
...
useragent => sub {
my $ua = LWP::UserAgent->new;
$ua->agent('MyUberAgent/0.23');
return $ua
},
...
);
# if the API require authentification, the module will handle basic
# authentication for you
net_api_declare my_api => (
...
authentication => 1,
...
);
# if the authentication is more complex, you can delegate to your own method
1;
my $obj = My::Net::API->new();
$obj->api_base_url('http://...');
$obj->foo(user => $user);
=head1 DESCRIPTION
Net::HTTP::API is a module to help to easily create a client for a web API.
This module is heavily inspired by what L<Net::Twitter> does.
B<THIS MODULE IS IN ITS BETA QUALITY. THE API MAY CHANGE IN THE FUTURE>
The following roles are added to your class:
=over 4
=item B<Net::HTTP::API::Role::UserAgent>
=item B<Net::HTTP::API::Role::Format>
=item B<Net::HTTP::API::Role::Authentication>
=item B<Net::HTTP::API::Role::Serialization>
=item B<Net::HTTP::API::Role::Request>
=back
The following attributes are added to your class:
=over 4
=item B<api_base_url>
=item B<api_format>
=item B<api_username>
=item B<api_passord>
=item B<authentication>
=item B<authentication_method>
=back
The following methods are added to your class:
=over 4
=item B<http_request>
=item B<get_content>
=item B<serialize>
=item B<deserialize>
=item B<content_type>
=back
=head2 METHODS
=over 4
=item B<net_api_declare>
net_api_declare backtype => (
base_url => 'http://api....',
format => 'json',
format_mode => 'append',
);
=over 2
=item B<api_base_url>
The base url for all the API's calls. This will set the B<api_base_url> attribut in your class. Can be set at the object creation or before calling an API method.
=item B<api_format>
The format for the API's calls. This will set the B<api_format> attribut to your class. Value can be:
=over 2
=item B<json>
=item B<yaml>
=item B<xml>
=back
=item B<api_format_mode>
How the format is handled. B<append> will add B<.$format> to the query, B<content-type> will set the content-type information to the header of the request. Should be one the following value:
=over 2
=item B<content-type>
=item B<append>
=back
=item B<api_useragent>
A L<LWP::UserAgent> object.
useragent => sub {
my $ua = LWP::UserAgent->new;
$ua->agent( "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1");
return $ua;
}
=item B<authentication>
This is a boolean to tell if we must authenticate to use this API.
=item B<authentication_method>
The default authentication method only set an authorization header using the Basic Authentication Scheme. You can write your own authentication method:
net_api_declare foo => (
...
authentication_method => 'my_auth_method',
...
);
sub my_auth_method {
my ($self, $req) = @_; #$req is an HTTP::Request object
...
}
=back
=item B<net_api_method>
=over 2
=item B<description>
A string to describe the method (this is a documentation)
=item B<method>
HTTP method (GET, POST, PUT, DELETE)
=item B<path>
path of the query.
If you defined your path and params like this
net_api_method user_comments => (
...
path => '/user/:user/list/:date',
params => [qw/user date foo bar/],
...
);
and you call
$obj->user_comments(user => 'franck', date => 'today', foo => 1, bar => 2);
the url generated will look like
/user/franck/list/today/?foo=1&bar=2
=item B<params>
Arrayref of params.
=item B<required>
Arrayref of required params.
=item B<params_in_url>
When you do a post, the content may have to be sent as arguments in the url, and not as content in the header.
=back
=back
