NAME
Net::HTTP::API - Easily create client for net API
VERSION
version 0.14
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);
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 Net::Twitter does.
THIS MODULE IS IN ITS BETA QUALITY. THE API MAY CHANGE IN THE FUTURE
The following roles are added to your class:
- 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
The following attributes are added to your class:
- api_base_url
- api_format
- api_username
- api_passord
- authentication
- authentication_method
The following methods are added to your class:
- http_request
- get_content
- serialize
- deserialize
- content_type
METHODS
- net_api_declare
-
net_api_declare backtype => ( base_url => 'http://api....', format => 'json', format_mode => 'append', );
- api_base_url
-
The base url for all the API's calls. This will set the api_base_url attribut in your class. Can be set at the object creation or before calling an API method.
- api_format
-
The format for the API's calls. This will set the api_format attribut to your class. Value can be:
- json
- yaml
- xml
- api_format_mode
-
How the format is handled. append will add .$format to the query, content-type will set the content-type information to the header of the request. Should be one the following value:
- api_useragent
-
A 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; }
- authentication
-
This is a boolean to tell if we must authenticate to use this API.
- 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 ... }
- net_api_method
-
- description
-
A string to describe the method (this is a documentation)
- method
-
HTTP method (GET, POST, PUT, DELETE)
- 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
- params
-
Arrayref of params.
- required
-
Arrayref of required params.
- 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.
AUTHOR
franck cuny <franck@lumberjaph.net>
COPYRIGHT AND LICENSE
This software is copyright (c) 2010 by linkfluence.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.