NAME

MooseX::Net::API - Easily create client for net API

SYNOPSIS

package My::Net::API;
use Moose;
use MooseX::Net::API;

# we declare an API, the base_url is http://exemple.com/api
# the format is json and it will be happened to the query
# You can set base_url later, calling $obj->api_base_url('http://..')
net_api_declare my_api => (
  base_url   => 'http://exemple.com/api',
  format     => 'json',
  format_api => 'append',
);

# calling $obj->foo will call http://exemple.com/api/foo?user=$user&group=$group
net_api_method foo => (
  description => 'this get foo',
  method      => 'GET',
  path        => '/foo/',
  params      => [qw/user group/],
  required    => [qw/user/],
);

# you can create your own useragent
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

MooseX::Net::API is 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

METHODS

net_api_declare

net_api_declare backtype => (
  base_url    => 'http://api....',
  format      => 'json',
  format_mode => 'append',
);

base_url (required)

The base url for all the API's calls. This will add an api_base_url attribut to your class.

format (required, must be either xml, json or yaml)

The format for the API's calls. This will add an api_format attribut to your class.

format_mode (required, must be 'append' or 'content-type')

How the format is handled. append will add .json to the query, content-type will add the content-type information to the header of the request.

useragent (optional, by default it's 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 (optional)

This is a boolean to tell if we must authenticate to use this API.

authentication_method (optional)

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
  ...
  return $req;
}

net_api_method

description [string]

description of the method (this is a documentation)

method [string]

HTTP method (GET, POST, PUT, DELETE)

path [string]

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 generetad will look like

/user/franck/list/today/?foo=1&bar=2

params [arrayref]

list of params.

required [arrayref]

list of required params.

authentication (optional)

should we do an authenticated call

params_in_url (optional)

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>

SEE ALSO

LICENSE

Copyright 2009 by Linkfluence

http://linkfluence.net

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.