Net::Twitter::Lite - A perl interface to the Twitter API

  use Net::Twitter::Lite;

  my $nt = Net::Twitter::Lite->new(
      username => $user,
      password => $password
  );

  my $result = eval { $nt->update('Hello, world!') };

  eval {
      my $statuses = $nt->friends_timeline({ since_id => $high_water, count => 100 });
      for my $status ( @$statuses ) {
          print "$status->{created_at} <$status->{user}{screen_name}> $status->{text}\n";
      }
  };
  warn "$@\n" if $@;

    $nt = Net::Twitter::Lite->new(netrc_machine => 'twitter.com', netrc => 1);
    # -or-
    $nt = Net::Twitter::Lite->new(netrc => 'twitter.com');

  # DON'T!
  my $friends = $nt->friends();
  if ( $friends ) {
      # process $friends
  }

  # DO!
  my $friends = eval { $nt->friends() };
  if ( $friends ) {
      # process $friends
  }

  # DON'T!
  my $friends = $nt->friends();
  if ( $friends ) {
      # process $friends
  }
  else {
      my $error = $nt->get_error;
      if ( ref $error ) {
          if ( ref($error) eq 'HASH' && exists $error->{error} ) {
              $error = $error->{error};
          }
          else {
              $error = 'Unexpected error type ' . ref($error);
          }
      }
      else {
          $error = $nt->http_code() . ": " . $nt->http_message;
      }
      warn "$error\n";
  }

  # DO!
  eval {
      my $friends = $nt->friends();
      # process $friends
  };
  warn "$@\n" if $@;
  return;

  # DO!
  eval {
     my $friends = $nt->friends();
     # process $friends
  };
  if ( my $error = $@ ) {
      if ( blessed $error && $error->isa("Net::Twitter::Lite::Error)
           && $error->code() == 502 ) {
          $error = "Fail Whale!";
      }
      warn "$error\n";
  }

    $nt->update({ status => 'Hello world!' });

    $nt->update('Hello world!');

    $nt->update({ status => 'Hello world!', in_reply_to_status_id => $reply_to });

    $nt->friendship_exists({ user_a => $fred, user_b => $barney });
    $nt->friendship_exists($fred, $barney);

    $nt->friendship_exists($fred, $barney);
    $nt->relationship_exists($fred, $barney);
    $nt->follows($fred, $barney);

    $nt->follows({ user_a => $fred, user_b => $barney });

    $nt->create_friend('perl_api');    # screen name
    $nt->create_friend(1564061);       # numeric ID
    $nt->create_friend({ id => 'perl_api' });
    $nt->create_friend({ screen_name => 'perl_api' });
    $nt->create_friend({ user_id     => 1564061 });

    $nt->create_friend(911); # interpreted as screen name
    $nt->create_friend({ user_id => 911 }); # screen name: richellis

    eval {
        my $statuses = $nt->friends_timeline(); # this might die!

        for my $status ( @$statuses ) {
            #...
        }
    };
    if ( $@ ) {
        # friends_timeline encountered an error

        if ( blessed $@ && $@->isa('Net::Twitter::Lite::Error' ) {
            #... use the thrown error obj
            warn $@->error;
        }
        else {
            # something bad happened!
            die $@;
        }
    }

    eval { $nt->update($status) };
    if ( $@ ) {
        warn "update failed because: $@\n";
    }

  use Net::Twitter::Lite;

  my $nt = Net::Twitter::Lite->new(
      consumer_key    => "YOUR-CONSUMER-KEY",
      consumer_secret => "YOUR-CONSUMER-SECRET",
  );

  # You'll save the token and secret in cookie, config file or session database
  my($access_token, $access_token_secret) = restore_tokens();
  if ($access_token && $access_token_secret) {
      $nt->access_token($access_token);
      $nt->access_token_secret($access_token_secret);
  }

  unless ( $nt->authorized ) {
      # The client is not yet authorized: Do it now
      print "Authorize this app at ", $nt->get_authorization_url, " and enter the PIN#\n";

      my $pin = <STDIN>; # wait for input
      chomp $pin;

      my($access_token, $access_token_secret, $user_id, $screen_name) =
          $nt->request_access_token(verifier => $pin);
      save_tokens($access_token, $access_token_secret); # if necessary
  }

  # Everything's ready

  sub twitter_authorize : Local {
      my($self, $c) = @_;

      my $nt = Net::Twitter::Lite->new(%param);
      my $url = $nt->get_authorization_url(callback => $callbackurl);

      $c->response->cookies->{oauth} = {
          value => {
              token => $nt->request_token,
              token_secret => $nt->request_token_secret,
          },
      };

      $c->response->redirect($url);
  }

  sub twitter_auth_callback : Local {
      my($self, $c) = @_;

      my %cookie = $c->request->cookies->{oauth}->value;

      my $nt = Net::Twitter::Lite->new(%param);
      $nt->request_token($cookie{token});
      $nt->request_token_secret($cookie{token_secret});
      my $verifier = $c->req->param->{oauth_verifier};

      my($access_token, $access_token_secret, $user_id, $screen_name) =
          $nt->request_access_token(verifier => $verifier);

      # Save $access_token and $access_token_secret in the database associated with $c->user
  }

  sub make_tweet : Local {
      my($self, $c) = @_;

      my($access_token, $access_token_secret) = ...;

      my $nt = Net::Twitter::Lite->new(%param);
      $nt->access_token($access_token);
      $nt->access_token_secret($access_token_secret);

      # Now you can call any Net::Twitter::Lite API methods on $nt
      my $status = $c->req->param('status');
      my $res = $nt->update({ status => $status });
  }

package Net::Twitter::Lite;
use 5.005;
use warnings;
use strict;

our $VERSION = '0.10004';
$VERSION = eval { $VERSION };

use Carp;
use URI::Escape;
use JSON::Any qw/XS JSON/;
use HTTP::Request::Common;
use Net::Twitter::Lite::Error;
use Encode qw/encode_utf8/;

my $json_handler = JSON::Any->new(utf8 => 1);

sub new {
    my ($class, %args) = @_;

    my $netrc = delete $args{netrc};
    my $new = bless {
        apiurl                => 'http://api.twitter.com/1',
        searchapiurl          => 'http://search.twitter.com',
        search_trends_api_url => 'http://api.twitter.com/1',
        lists_api_url         => 'http://api.twitter.com/1',
        apirealm   => 'Twitter API',
        $args{identica} ? ( apiurl => 'http://identi.ca/api' ) : (),
        useragent  => __PACKAGE__ . "/$VERSION (Perl)",
        clientname => __PACKAGE__,
        clientver  => $VERSION,
        clienturl  => 'http://search.cpan.org/dist/Net-Twitter-Lite/',
        source     => 'twitterpm',
        useragent_class => 'LWP::UserAgent',
        useragent_args  => {},
        oauth_urls => {
            request_token_url  => "https://twitter.com/oauth/request_token",
            authentication_url => "https://twitter.com/oauth/authenticate",
            authorization_url  => "https://twitter.com/oauth/authorize",
            access_token_url   => "https://twitter.com/oauth/access_token",
            xauth_url          => "https://twitter.com/oauth/access_token",
        },
        netrc_machine => 'api.twitter.com',
        %args
    }, $class;


    if ( delete $args{ssl} ) {
        $new->{$_} =~ s/^http:/https:/
            for qw/apiurl searchapiurl search_trends_api_url lists_api_url/;
    }

    # get username and password from .netrc
    if ( $netrc ) {
        eval { require Net::Netrc; 1 }
            || croak "Net::Netrc is required for the netrc option";

        my $host = $netrc eq '1' ? $new->{netrc_machine} : $netrc;
        my $nrc = Net::Netrc->lookup($host)
            || croak "No .netrc entry for $host";

        @{$new}{qw/username password/} = $nrc->lpa;
    }

    $new->{ua} ||= do {
        eval "use $new->{useragent_class}";
        croak $@ if $@;

        $new->{useragent_class}->new(%{$new->{useragent_args}});
    };

    $new->{ua}->agent($new->{useragent});
    $new->{ua}->default_header('X-Twitter-Client'         => $new->{clientname});
    $new->{ua}->default_header('X-Twitter-Client-Version' => $new->{clientver});
    $new->{ua}->default_header('X-Twitter-Client-URL'     => $new->{clienturl});
    $new->{ua}->env_proxy;

    $new->{_authenticator} = exists $new->{consumer_key}
                           ? '_oauth_authenticated_request'
                           : '_basic_authenticated_request';

    $new->credentials(@{$new}{qw/username password/})
        if exists $new->{username} && exists $new->{password};

    return $new;
}

sub credentials {
    my $self = shift;
    my ($username, $password) = @_;

    croak "exected a username and password" unless @_ == 2;
    croak "OAuth authentication is in use"  if exists $self->{consumer_key};

    $self->{username} = $username;
    $self->{password} = $password;

    my $uri = URI->new($self->{apiurl});
    my $netloc = join ':', $uri->host, $uri->port;

    $self->{ua}->credentials($netloc, $self->{apirealm}, $username, $password);
}

# This is a hack. Rather than making Net::OAuth an install requirement for
# Net::Twitter::Lite, require it at runtime if any OAuth methods are used.  It
# simply returns the string 'Net::OAuth' after successfully requiring
# Net::OAuth.
sub _oauth {
    my $self = shift;

    return $self->{_oauth} ||= do {
        eval "use Net::OAuth 0.25";
        croak "Install Net::OAuth 0.25 or later for OAuth support" if $@;

        eval '$Net::OAuth::PROTOCOL_VERSION = Net::OAuth::PROTOCOL_VERSION_1_0A';
        die $@ if $@;

        'Net::OAuth';
    };
}

# simple check to see if we have access tokens; does not check to see if they are valid
sub authorized {
    my $self = shift;

    return defined $self->{access_token} && $self->{access_token_secret};
}

# OAuth token accessors
for my $method ( qw/
            access_token
            access_token_secret
            request_token
            request_token_secret
        / ) {
    no strict 'refs';
    *{__PACKAGE__ . "::$method"} = sub {
        my $self = shift;

        $self->{$method} = shift if @_;
        return $self->{$method};
    };
}

# OAuth url accessors
for my $method ( qw/
            request_token_url
            authentication_url
            authorization_url
            access_token_url
            xauth_url
        / ) {
    no strict 'refs';
    *{__PACKAGE__ . "::$method"} = sub {
        my $self = shift;

        $self->{oauth_urls}{$method} = shift if @_;
        return URI->new($self->{oauth_urls}{$method});
    };
}

# get the athorization or authentication url
sub _get_auth_url {
    my ($self, $which_url, %params ) = @_;

    $self->_request_request_token(%params);

    my $uri = $self->$which_url;
    $uri->query_form(oauth_token => $self->request_token);
    return $uri;
}

# get the authentication URL from Twitter
sub get_authentication_url { return shift->_get_auth_url(authentication_url => @_) }

# get the authorization URL from Twitter
sub get_authorization_url { return shift->_get_auth_url(authorization_url => @_) }

# common portion of all oauth requests
sub _make_oauth_request {
    my ($self, $type, %params) = @_;

    my $request = $self->_oauth->request($type)->new(
        version          => '1.0',
        consumer_key     => $self->{consumer_key},
        consumer_secret  => $self->{consumer_secret},
        request_method   => 'GET',
        signature_method => 'HMAC-SHA1',
        timestamp        => time,
        nonce            => time ^ $$ ^ int(rand 2**32),
        %params,
    );

    $request->sign;

    return $request;
}

# called by get_authorization_url to obtain request tokens
sub _request_request_token {
    my ($self, %params) = @_;

    my $uri = $self->request_token_url;
    $params{callback} ||= 'oob';
    my $request = $self->_make_oauth_request(
        'request token',
        request_url => $uri,
        %params,
    );

    my $res = $self->{ua}->get($request->to_url);
    die "GET $uri failed: ".$res->status_line
        unless $res->is_success;

    # reuse $uri to extract parameters from the response content
    $uri->query($res->content);
    my %res_param = $uri->query_form;

    $self->request_token($res_param{oauth_token});
    $self->request_token_secret($res_param{oauth_token_secret});
}

# exchange request tokens for access tokens; call with (verifier => $verifier)
sub request_access_token {
    my ($self, %params ) = @_;

    my $uri = $self->access_token_url;
    my $request = $self->_make_oauth_request(
        'access token',
        request_url => $uri,
        token       => $self->request_token,
        token_secret => $self->request_token_secret,
        %params, # verifier => $verifier
    );

    my $res = $self->{ua}->get($request->to_url);
    die "GET $uri failed: ".$res->status_line
        unless $res->is_success;

    # discard request tokens, they're no longer valid
    delete $self->{request_token};
    delete $self->{request_token_secret};

    # reuse $uri to extract parameters from content
    $uri->query($res->content);
    my %res_param = $uri->query_form;

    return (
        $self->access_token($res_param{oauth_token}),
        $self->access_token_secret($res_param{oauth_token_secret}),
        $res_param{user_id},
        $res_param{screen_name},
    );
}

# exchange username and password for access tokens
sub xauth {
    my ( $self, $username, $password ) = @_;

    my $uri = $self->xauth_url;
    my $request = $self->_make_oauth_request(
        'XauthAccessToken',
        request_url     => $uri,
        x_auth_username => $username,
        x_auth_password => $password,
        x_auth_mode     => 'client_auth',
    );

    my $res = $self->{ua}->get($request->to_url);
    die "GET $uri failed: ".$res->status_line
        unless $res->is_success;

    # reuse $uri to extract parameters from content
    $uri->query($res->content);
    my %res_param = $uri->query_form;

    return (
        $self->access_token($res_param{oauth_token}),
        $self->access_token_secret($res_param{oauth_token_secret}),
        $res_param{user_id},
        $res_param{screen_name},
    );
}

# common call for both Basic Auth and OAuth
sub _authenticated_request {
    my $self = shift;

    my $authenticator = $self->{_authenticator};
    $self->$authenticator(@_);
}

sub _encode_args {
    my $args = shift;

    # Values need to be utf-8 encoded.  Because of a perl bug, exposed when
    # client code does "use utf8", keys must also be encoded.
    # see: http://www.perlmonks.org/?node_id=668987
    # and: http://perl5.git.perl.org/perl.git/commit/eaf7a4d2
    return { map { utf8::upgrade($_) unless ref($_); $_ } %$args };
}

sub _oauth_authenticated_request {
    my ($self, $http_method, $uri, $args, $authenticate) = @_;

    delete $args->{source}; # not necessary with OAuth requests

    my $is_multipart = grep { ref } %$args;

    my $msg;
    if ( $authenticate && $self->authorized ) {
        local $Net::OAuth::SKIP_UTF8_DOUBLE_ENCODE_CHECK = 1;

        my $request = $self->_make_oauth_request(
            'protected resource',
            request_url    => $uri,
            request_method => $http_method,
            token          => $self->access_token,
            token_secret   => $self->access_token_secret,
            extra_params   => $is_multipart ? {} : $args,
        );

        if ( $http_method =~ /^(?:GET|DELETE)$/ ) {
            $msg = HTTP::Request->new($http_method, $request->to_url);
        }
        elsif ( $http_method eq 'POST' ) {
            $msg = $is_multipart
                 ? POST($request->request_url,
                        Authorization => $request->to_authorization_header,
                        Content_Type  => 'form-data',
                        Content       => [ %$args ],
                   )
                 : POST($$uri, Content => $request->to_post_body)
                 ;
        }
        else {
            croak "unexpected http_method: $http_method";
        }
    }
    elsif ( $http_method eq 'GET' ) {
        $uri->query_form($args);
        $args = {};
        $msg = GET($uri);
    }
    elsif ( $http_method eq 'POST' ) {
        my $encoded_args = { %$args };
        _encode_args($encoded_args);
        $msg = $self->_mk_post_msg($uri, $args);
    }
    else {
        croak "unexpected http_method: $http_method";
    }

    return $self->{ua}->request($msg);
}

sub _basic_authenticated_request {
    my ($self, $http_method, $uri, $args, $authenticate) = @_;

    _encode_args($args);

    my $msg;
    if ( $http_method =~ /^(?:GET|DELETE)$/ ) {
        $uri->query_form($args);
        $msg = HTTP::Request->new($http_method, $uri);
    }
    elsif ( $http_method eq 'POST' ) {
        $msg = $self->_mk_post_msg($uri, $args);
    }
    else {
        croak "unexpected HTTP method: $http_method";
    }

    if ( $authenticate && $self->{username} && $self->{password} ) {
        $msg->headers->authorization_basic(@{$self}{qw/username password/});
    }

    return $self->{ua}->request($msg);
}

sub _mk_post_msg {
    my ($self, $uri, $args) = @_;

    # if any of the arguments are (array) refs, use form-data
    return (grep { ref } values %$args)
         ? POST($uri, Content_Type => 'form-data', Content => [ %$args ])
         : POST($uri, $args);
}

{ ### scope $api_def

my $api_def = [
    [ REST => [
        [ 'account_settings', {
            aliases     => [ qw// ],
            path        => 'account/settings',
            method      => 'GET',
            params      => [ qw// ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'account_totals', {
            aliases     => [ qw// ],
            path        => 'account/totals',
            method      => 'GET',
            params      => [ qw// ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'all_lists', {
            aliases     => [ qw// ],
            path        => 'lists/all',
            method      => 'GET',
            params      => [ qw/id user_id screen_name/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'block_exists', {
            aliases     => [ qw// ],
            path        => 'blocks/exists/:id',
            method      => 'GET',
            params      => [ qw/id user_id screen_name include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'blocking', {
            aliases     => [ qw// ],
            path        => 'blocks/blocking',
            method      => 'GET',
            params      => [ qw/page include_entities/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'blocking_ids', {
            aliases     => [ qw// ],
            path        => 'blocks/blocking/ids',
            method      => 'GET',
            params      => [ qw// ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'create_block', {
            aliases     => [ qw// ],
            path        => 'blocks/create/:id',
            method      => 'POST',
            params      => [ qw/id user_id screen_name include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'create_favorite', {
            aliases     => [ qw// ],
            path        => 'favorites/create/:id',
            method      => 'POST',
            params      => [ qw/id include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'create_friend', {
            aliases     => [ qw/follow_new/ ],
            path        => 'friendships/create/:id',
            method      => 'POST',
            params      => [ qw/id user_id screen_name follow include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities follow/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'create_saved_search', {
            aliases     => [ qw// ],
            path        => 'saved_searches/create',
            method      => 'POST',
            params      => [ qw/query/ ],
            required    => [ qw/query/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'destroy_block', {
            aliases     => [ qw// ],
            path        => 'blocks/destroy/:id',
            method      => 'POST',
            params      => [ qw/id user_idscreen_name/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'destroy_direct_message', {
            aliases     => [ qw// ],
            path        => 'direct_messages/destroy/:id',
            method      => 'POST',
            params      => [ qw/id include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'destroy_favorite', {
            aliases     => [ qw// ],
            path        => 'favorites/destroy/:id',
            method      => 'POST',
            params      => [ qw/id include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'destroy_friend', {
            aliases     => [ qw/unfollow/ ],
            path        => 'friendships/destroy/:id',
            method      => 'POST',
            params      => [ qw/id user_id screen_name include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'destroy_saved_search', {
            aliases     => [ qw// ],
            path        => 'saved_searches/destroy/:id',
            method      => 'POST',
            params      => [ qw/id/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'destroy_status', {
            aliases     => [ qw// ],
            path        => 'statuses/destroy/:id',
            method      => 'POST',
            params      => [ qw/id trim_user include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/trim_user include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'direct_messages', {
            aliases     => [ qw// ],
            path        => 'direct_messages',
            method      => 'GET',
            params      => [ qw/since_id max_id count page include_entities/ ],
            required    => [ qw/include_entities/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'disable_notifications', {
            aliases     => [ qw// ],
            path        => 'notifications/leave/:id',
            method      => 'POST',
            params      => [ qw/id screen_name include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'downtime_schedule', {
            aliases     => [ qw// ],
            path        => 'help/downtime_schedule',
            method      => 'GET',
            params      => [ qw// ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 1,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'enable_notifications', {
            aliases     => [ qw// ],
            path        => 'notifications/follow/:id',
            method      => 'POST',
            params      => [ qw/id screen_name include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'end_session', {
            aliases     => [ qw// ],
            path        => 'account/end_session',
            method      => 'POST',
            params      => [ qw// ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'favorites', {
            aliases     => [ qw// ],
            path        => 'favorites/:id',
            method      => 'GET',
            params      => [ qw/id page include_entities/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'followers', {
            aliases     => [ qw// ],
            path        => 'statuses/followers/:id',
            method      => 'GET',
            params      => [ qw/id user_id screen_name cursor include_entities/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'followers_ids', {
            aliases     => [ qw// ],
            path        => 'followers/ids/:id',
            method      => 'GET',
            params      => [ qw/id user_id screen_name cursor/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'friends', {
            aliases     => [ qw/following/ ],
            path        => 'statuses/friends/:id',
            method      => 'GET',
            params      => [ qw/id user_id screen_name cursor include_entities/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'friends_ids', {
            aliases     => [ qw/following_ids/ ],
            path        => 'friends/ids/:id',
            method      => 'GET',
            params      => [ qw/id user_id screen_name cursor/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'friends_timeline', {
            aliases     => [ qw/following_timeline/ ],
            path        => 'statuses/friends_timeline',
            method      => 'GET',
            params      => [ qw/since_id max_id count page skip_user trim_user include_entities include_rts/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/skip_user trim_user include_entities include_rts/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'friendship_exists', {
            aliases     => [ qw/relationship_exists follows/ ],
            path        => 'friendships/exists',
            method      => 'GET',
            params      => [ qw/user_a user_b/ ],
            required    => [ qw/user_a user_b/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'friendships_incoming', {
            aliases     => [ qw// ],
            path        => 'friendships/incoming',
            method      => 'GET',
            params      => [ qw/cursor/ ],
            required    => [ qw/cursor/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'friendships_outgoing', {
            aliases     => [ qw// ],
            path        => 'friendships/outgoing',
            method      => 'GET',
            params      => [ qw/cursor/ ],
            required    => [ qw/cursor/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'geo_id', {
            aliases     => [ qw// ],
            path        => 'geo/id/:id',
            method      => 'GET',
            params      => [ qw/id/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'home_timeline', {
            aliases     => [ qw// ],
            path        => 'statuses/home_timeline',
            method      => 'GET',
            params      => [ qw/since_id max_id count page skip_user exclude_replies contributor_details include_rts include_entities trim_user include_my_retweet/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/skip_user exclude_replies contributor_details include_rts include_entities trim_user include_my_retweet/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'lookup_friendships', {
            aliases     => [ qw// ],
            path        => 'friendships/lookup',
            method      => 'GET',
            params      => [ qw/user_id screen_name/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'lookup_users', {
            aliases     => [ qw// ],
            path        => 'users/lookup',
            method      => 'GET',
            params      => [ qw/user_id screen_name include_entities/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'mentions', {
            aliases     => [ qw/replies/ ],
            path        => 'statuses/replies',
            method      => 'GET',
            params      => [ qw/since_id max_id count page trim_user include_rts include_entities/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/trim_user include_rts include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'new_direct_message', {
            aliases     => [ qw// ],
            path        => 'direct_messages/new',
            method      => 'POST',
            params      => [ qw/user text screen_name user_id include_entities/ ],
            required    => [ qw/user text/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'no_retweet_ids', {
            aliases     => [ qw// ],
            path        => 'friendships/no_retweet_ids',
            method      => 'GET',
            params      => [ qw// ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'public_timeline', {
            aliases     => [ qw// ],
            path        => 'statuses/public_timeline',
            method      => 'GET',
            params      => [ qw/skip_user trim_user include_entities/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/skip_user trim_user include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'rate_limit_status', {
            aliases     => [ qw// ],
            path        => 'account/rate_limit_status',
            method      => 'GET',
            params      => [ qw// ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'related_results', {
            aliases     => [ qw// ],
            path        => 'related_results/show/:id',
            method      => 'GET',
            params      => [ qw/id/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'report_spam', {
            aliases     => [ qw// ],
            path        => 'report_spam',
            method      => 'POST',
            params      => [ qw/id user_id screen_name include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'retweet', {
            aliases     => [ qw// ],
            path        => 'statuses/retweet/:id',
            method      => 'POST',
            params      => [ qw/id include_entities trim_user/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities trim_user/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'retweeted_by', {
            aliases     => [ qw// ],
            path        => 'statuses/:id/retweeted_by',
            method      => 'GET',
            params      => [ qw/id count page trim_user include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities trim_user/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'retweeted_by_ids', {
            aliases     => [ qw// ],
            path        => 'statuses/:id/retweeted_by/ids',
            method      => 'GET',
            params      => [ qw/id count page trim_user include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities trim_user/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'retweeted_by_me', {
            aliases     => [ qw// ],
            path        => 'statuses/retweeted_by_me',
            method      => 'GET',
            params      => [ qw/since_id max_id count page trim_user include_entities/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/trim_user include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'retweeted_by_user', {
            aliases     => [ qw// ],
            path        => 'statuses/retweeted_by_user',
            method      => 'GET',
            params      => [ qw/id user_id screen_name/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'retweeted_to_me', {
            aliases     => [ qw// ],
            path        => 'statuses/retweeted_to_me',
            method      => 'GET',
            params      => [ qw/since_id max_id count page/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'retweeted_to_user', {
            aliases     => [ qw// ],
            path        => 'statuses/retweeted_to_user',
            method      => 'GET',
            params      => [ qw/id user_id screen_name/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'retweets', {
            aliases     => [ qw// ],
            path        => 'statuses/retweets/:id',
            method      => 'GET',
            params      => [ qw/id count trim_user include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/trim_user include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'retweets_of_me', {
            aliases     => [ qw/retweeted_of_me/ ],
            path        => 'statuses/retweets_of_me',
            method      => 'GET',
            params      => [ qw/since_id max_id count page trim_user include_entities/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/trim_user include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'reverse_geocode', {
            aliases     => [ qw// ],
            path        => 'geo/reverse_geocode',
            method      => 'GET',
            params      => [ qw/lat long accuracy granularity max_results/ ],
            required    => [ qw/lat long/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'saved_searches', {
            aliases     => [ qw// ],
            path        => 'saved_searches',
            method      => 'GET',
            params      => [ qw// ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'sent_direct_messages', {
            aliases     => [ qw// ],
            path        => 'direct_messages/sent',
            method      => 'GET',
            params      => [ qw/since_id max_id page count include_entities/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'show_direct_message', {
            aliases     => [ qw// ],
            path        => 'direct_messages/show/:id',
            method      => 'GET',
            params      => [ qw/id include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'show_friendship', {
            aliases     => [ qw/show_relationship/ ],
            path        => 'friendships/show',
            method      => 'GET',
            params      => [ qw/source_id source_screen_name target_id target_id_name/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'show_saved_search', {
            aliases     => [ qw// ],
            path        => 'saved_searches/show/:id',
            method      => 'GET',
            params      => [ qw/id/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'show_status', {
            aliases     => [ qw// ],
            path        => 'statuses/show/:id',
            method      => 'GET',
            params      => [ qw/id trim_user include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/trim_user include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'show_user', {
            aliases     => [ qw// ],
            path        => 'users/show/:id',
            method      => 'GET',
            params      => [ qw/id screen_name include_entities/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'suggestion_categories', {
            aliases     => [ qw// ],
            path        => 'users/suggestions',
            method      => 'GET',
            params      => [ qw// ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'test', {
            aliases     => [ qw// ],
            path        => 'help/test',
            method      => 'GET',
            params      => [ qw// ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'trends', {
            aliases     => [ qw// ],
            path        => 'trends',
            method      => 'GET',
            params      => [ qw// ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 0,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'trends_available', {
            aliases     => [ qw// ],
            path        => 'trends/available',
            method      => 'GET',
            params      => [ qw/lat long/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 0,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'trends_current', {
            aliases     => [ qw// ],
            path        => 'trends/current',
            method      => 'GET',
            params      => [ qw/exclude/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 0,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'trends_daily', {
            aliases     => [ qw// ],
            path        => 'trends/daily',
            method      => 'GET',
            params      => [ qw/date exclude/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 0,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'trends_location', {
            aliases     => [ qw// ],
            path        => 'trends/:woeid',
            method      => 'GET',
            params      => [ qw/woeid/ ],
            required    => [ qw/woeid/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 0,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'trends_weekly', {
            aliases     => [ qw// ],
            path        => 'trends/weekly',
            method      => 'GET',
            params      => [ qw/date exclude/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 0,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'update', {
            aliases     => [ qw// ],
            path        => 'statuses/update',
            method      => 'POST',
            params      => [ qw/status lat long place_id display_coordinates in_reply_to_status_id trim_user include_entities/ ],
            required    => [ qw/status/ ],
            add_source  => 1,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/display_coordinates trim_user include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'update_delivery_device', {
            aliases     => [ qw// ],
            path        => 'account/update_delivery_device',
            method      => 'POST',
            params      => [ qw/device/ ],
            required    => [ qw/device/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'update_friendship', {
            aliases     => [ qw// ],
            path        => 'friendships/update',
            method      => 'POST',
            params      => [ qw/id user_id screen_name device retweets/ ],
            required    => [ qw/id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/device retweets/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'update_location', {
            aliases     => [ qw// ],
            path        => 'account/update_location',
            method      => 'POST',
            params      => [ qw/location/ ],
            required    => [ qw/location/ ],
            add_source  => 0,
            deprecated  => 1,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'update_profile', {
            aliases     => [ qw// ],
            path        => 'account/update_profile',
            method      => 'POST',
            params      => [ qw/name email url location description include_entities/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'update_profile_background_image', {
            aliases     => [ qw// ],
            path        => 'account/update_profile_background_image',
            method      => 'POST',
            params      => [ qw/image use/ ],
            required    => [ qw/image/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/use/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'update_profile_colors', {
            aliases     => [ qw// ],
            path        => 'account/update_profile_colors',
            method      => 'POST',
            params      => [ qw/profile_background_color profile_text_color profile_link_color profile_sidebar_fill_color profile_sidebar_border_color/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'update_profile_image', {
            aliases     => [ qw// ],
            path        => 'account/update_profile_image',
            method      => 'POST',
            params      => [ qw/image/ ],
            required    => [ qw/image/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'user_suggestions', {
            aliases     => [ qw/follow_suggestions/ ],
            path        => 'users/suggestions/:category/members',
            method      => 'GET',
            params      => [ qw/category lang/ ],
            required    => [ qw/category/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'apiurl',
        } ],
        [ 'user_timeline', {
            aliases     => [ qw// ],
            path        => 'statuses/user_timeline/:id',
            method      => 'GET',
            params      => [ qw/id user_id screen_name since_id max_id count page skip_user trim_user include_entities include_rts/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/skip_user trim_user include_entities include_rts/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'users_search', {
            aliases     => [ qw/find_people search_users/ ],
            path        => 'users/search',
            method      => 'GET',
            params      => [ qw/q per_page page include_entities/ ],
            required    => [ qw/q/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
        [ 'verify_credentials', {
            aliases     => [ qw// ],
            path        => 'account/verify_credentials',
            method      => 'GET',
            params      => [ qw/include_entities/ ],
            required    => [ qw// ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw/include_entities/ ],
        base_url_method => 'apiurl',
        } ],
    ] ],
    [ Search => [
        [ 'search', {
            aliases     => [ qw// ],
            path        => 'search',
            method      => 'GET',
            params      => [ qw/q callback lang locale rpp page since_id until geocode show_user result_type/ ],
            required    => [ qw/q/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 0,
            booleans    => [ qw// ],
        base_url_method => 'searchapiurl',
        } ],
    ] ],
    [ Lists => [
        [ 'add_list_member', {
            aliases     => [ qw// ],
            path        => ':user/:list_id/members',
            method      => 'POST',
            params      => [ qw/user list_id id/ ],
            required    => [ qw/user list_id id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'create_list', {
            aliases     => [ qw// ],
            path        => ':user/lists',
            method      => 'POST',
            params      => [ qw/user name mode description/ ],
            required    => [ qw/user name/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'delete_list', {
            aliases     => [ qw// ],
            path        => ':user/lists/:list_id',
            method      => 'DELETE',
            params      => [ qw/user list_id/ ],
            required    => [ qw/user list_id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'delete_list_member', {
            aliases     => [ qw/remove_list_member/ ],
            path        => ':user/:list_id/members',
            method      => 'DELETE',
            params      => [ qw/user list_id id/ ],
            required    => [ qw/user list_id id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'get_list', {
            aliases     => [ qw// ],
            path        => ':user/lists/:list_id',
            method      => 'GET',
            params      => [ qw/user list_id/ ],
            required    => [ qw/user list_id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'get_lists', {
            aliases     => [ qw/list_lists/ ],
            path        => ':user/lists',
            method      => 'GET',
            params      => [ qw/user cursor/ ],
            required    => [ qw/user/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'is_list_member', {
            aliases     => [ qw// ],
            path        => ':user/:list_id/members/:id',
            method      => 'GET',
            params      => [ qw/user list_id id/ ],
            required    => [ qw/user list_id id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'is_list_subscriber', {
            aliases     => [ qw/is_subscribed_list/ ],
            path        => ':user/:list_id/subscribers/:id',
            method      => 'GET',
            params      => [ qw/user list_id id/ ],
            required    => [ qw/user list_id id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'list_members', {
            aliases     => [ qw// ],
            path        => ':user/:list_id/members',
            method      => 'GET',
            params      => [ qw/user list_id id cursor/ ],
            required    => [ qw/user list_id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'list_memberships', {
            aliases     => [ qw// ],
            path        => ':user/lists/memberships',
            method      => 'GET',
            params      => [ qw/user cursor/ ],
            required    => [ qw/user/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'list_statuses', {
            aliases     => [ qw// ],
            path        => ':user/lists/:list_id/statuses',
            method      => 'GET',
            params      => [ qw/user list_id since_id max_id per_page page/ ],
            required    => [ qw/user list_id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'list_subscribers', {
            aliases     => [ qw// ],
            path        => ':user/:list_id/subscribers',
            method      => 'GET',
            params      => [ qw/user list_id id cursor/ ],
            required    => [ qw/user list_id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'list_subscriptions', {
            aliases     => [ qw// ],
            path        => ':user/lists/subscriptions',
            method      => 'GET',
            params      => [ qw/user cursor/ ],
            required    => [ qw/user/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'members_create_all', {
            aliases     => [ qw/add_list_members/ ],
            path        => ':user/:list_id/members/create_all',
            method      => 'POST',
            params      => [ qw/user list_id screen_name user_id/ ],
            required    => [ qw/user list_id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'subscribe_list', {
            aliases     => [ qw// ],
            path        => ':user/:list_id/subscribers',
            method      => 'POST',
            params      => [ qw/user list_id/ ],
            required    => [ qw/user list_id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'unsubscribe_list', {
            aliases     => [ qw// ],
            path        => ':user/:list_id/subscribers',
            method      => 'DELETE',
            params      => [ qw/user list_id/ ],
            required    => [ qw/user list_id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
        [ 'update_list', {
            aliases     => [ qw// ],
            path        => ':user/lists/:list_id',
            method      => 'POST',
            params      => [ qw/user list_id name mode description/ ],
            required    => [ qw/user list_id/ ],
            add_source  => 0,
            deprecated  => 0,
            authenticate => 1,
            booleans    => [ qw// ],
        base_url_method => 'lists_api_url',
        } ],
    ] ],
];

my $with_url_arg = sub {
    my ($path, $args) = @_;

    if ( defined(my $id = delete $args->{id}) ) {
        $path .= uri_escape($id);
    }
    else {
        chop($path);
    }
    return $path;
};

while ( @$api_def ) {
    my $api = shift @$api_def;
    my $api_name = shift @$api;
    my $methods = shift @$api;

    for my $method ( @$methods ) {
        my $name    = shift @$method;
        my %options = %{ shift @$method };

        my ($arg_names, $path) = @options{qw/required path/};
        $arg_names = $options{params} if @$arg_names == 0 && @{$options{params}} == 1;

        my $modify_path = $path =~ s,/id$,/, ? $with_url_arg : sub { $_[0] };

        my $code = sub {
            my $self = shift;

            # copy callers args since we may add ->{source}
            my $args = ref $_[-1] eq 'HASH' ? { %{pop @_} } : {};

            croak sprintf "$name expected %d args", scalar @$arg_names if @_ > @$arg_names;

            # promote positional args to named args
            for ( my $i = 0; @_; ++$i ) {
                my $param = $arg_names->[$i];
                croak "duplicate param $param: both positional and named"
                    if exists $args->{$param};

                $args->{$param} = shift;
            }

            $args->{source} ||= $self->{source} if $options{add_source};

            my $authenticate = exists $args->{authenticate}  ? delete $args->{authenticate}
                             : $options{authenticate}
                             ;
            # promote boolean parameters
            for my $boolean_arg ( @{ $options{booleans} } ) {
                if ( exists $args->{$boolean_arg} ) {
                    next if $args->{$boolean_arg} =~ /^true|false$/;
                    $args->{$boolean_arg} = $args->{$boolean_arg} ? 'true' : 'false';
                }
            }

            # Workaround Twitter bug: any value passed for skip_user is treated as true.
            # The only way to get 'false' is to not pass the skip_user at all.
            delete $args->{skip_user} if exists $args->{skip_user} && $args->{skip_user} eq 'false';

            # replace placeholder arguments
            my $local_path = $path;
            $local_path =~ s,/:id$,, unless exists $args->{id}; # remove optional trailing id
            $local_path =~ s/:(\w+)/delete $args->{$1} or croak "required arg '$1' missing"/eg;

            my $uri = URI->new($self->{$options{base_url_method}} . "/$local_path.json");

            return $self->_parse_result(
                $self->_authenticated_request($options{method}, $uri, $args, $authenticate)
            );
        };

        no strict 'refs';
        *{__PACKAGE__ . "::$_"} = $code for $name, @{$options{aliases}};
    }
}

# catch expected error and promote it to an undef
for ( qw/list_members is_list_member list_subscribers is_list_subscriber/ ) {
    my $orig = __PACKAGE__->can($_) or die;

    my $code = sub {
        my $r = eval { $orig->(@_) };
        if ( $@ ) {
            return if $@ =~ /The specified user is not a (?:memb|subscrib)er of this list/;

            die $@;
        }

        return $r;
    };

    no strict 'refs';
    no warnings 'redefine';
    *{__PACKAGE__ . "::$_"} = $code;
}

# special case parameter handling for lookup_users
for ( qw/lookup_users/ ) {
    my $orig = __PACKAGE__->can($_) or die;

    my $code = sub {
        my $self = shift;

        my $args = ref $_[-1] eq 'HASH' ? pop @_ : {};
        $args = { %$args, @_ };

        for ( qw/screen_name user_id/ ) {
            $args->{$_} = join(',' => @{ $args->{$_} }) if ref $args->{$_} eq 'ARRAY';
        }

        return $orig->($self, $args);
    };

    no strict 'refs';
    no warnings 'redefine';
    *{__PACKAGE__ . "::$_"} = $code;
}



} ### end scope for $api_def

sub _from_json {
    my ($self, $json) = @_;

    return eval { $json_handler->from_json($json) };
}

sub _parse_result {
    my ($self, $res) = @_;

    # workaround for Laconica API returning bools as strings
    # (Fixed in Laconi.ca 0.7.4)
    my $content = $res->content;
    $content =~ s/^"(true|false)"$/$1/;

    my $obj = $self->_from_json($content);

    # Twitter sometimes returns an error with status code 200
    if ( $obj && ref $obj eq 'HASH' && exists $obj->{error} ) {
        die Net::Twitter::Lite::Error->new(twitter_error => $obj, http_response => $res);
    }

    return $obj if $res->is_success && defined $obj;

    my $error = Net::Twitter::Lite::Error->new(http_response => $res);
    $error->twitter_error($obj) if ref $obj;

    die $error;
}

1;

__END__