NAME

    Twitter::API - A Twitter REST API library for Perl

VERSION

    version 0.0102

SYNOPSIS

        ### Common usage ###
    
        use Twitter::API;
        my $client = Twitter::API->new_with_traits(
            traits              => 'Enchilada',
            consumer_key        => $YOUR_CONSUMER_KEY,
            consumer_secret     => $YOUR_CONSUMER_SECRET,
            access_token        => $YOUR_ACCESS_TOKEN
            access_token_secret => $YOUR_ACCESS_TOKEN_SECRET,
        );
    
        my $me   = $client->verify_credentials;
        my $user = $client->show_user('twitter');
    
        # In list context, both the Twitter API result and a Twitter::API::Context
        # object are returned.
        my ($r, $context) = $client->home_timeline({ count => 200, trim_user => 1 });
        my $remaning = $context->rate_limit_remaining;
        my $until    = $context->rate_limit_reset;
    
    
        ### No frills ###
    
        my $client = Twitter::API->new(
            consumer_key    => $YOUR_CONSUMER_KEY,
            consumer_secret => $YOUR_CONSUMER_SECRET,
        );
    
        my $r = $client->get('account/verify_credentials', {
            -token        => $an_access_token,
            -token_secret => $an_access_token_secret,
        });
    
        ### Error handling ###
    
        use Twitter::API::Util 'is_twitter_api_error';
        use Try::Tiny;
    
        try {
            my $r = $client->verify_credentials;
        }
        catch {
            die $_ unless is_twitter_api_error($_);
    
            # The error object includes plenty of information
            say $_->http_request->as_string;
            say $_->http_response->as_string;
            say 'No use retrying right away' if $_->is_permanent_error;
            if ( $_->is_token_error ) {
                say "There's something wrong with this token."
            }
            if ( $_->twitter_error_code == 326 ) {
                say "Oops! Twitter thinks you're spam bot!";
            }
        };

DESCRIPTION

    Twitter::API provides an interface to the Twitter REST API for perl.

    Features:

      * full support for all Twitter REST API endpoints

      * not dependent on a new distribution for new endpoint support

      * optionally specify access tokens per call; no need to construct a
      new client to use different tokens

      * error handling via an exception object that captures the full
      reqest/response context

      * full support for OAuth handshake and xauth authentication

    Additionl features are availble via optional traits:

      * convenient methods for API endpoints with simplified argument
      handling via ApiMethods

      * normalized booleans (Twitter likes 'true' and 'false', except when
      it doesn't) via NormalizeBooleans

      * automatic decoding of HTML entities via DecodeHtmlEntities

      * automatic retry on transient errors via RetryOnError

      * "the whole enchilada" combines all the above traits via Enchilada

      * app-only (OAuth2) support via AppAuth

    Some featuers are provided by separate distributions to avoid
    additional dependencies most users won't want or need:

      * async support via subclass Twitter::API::AnyEvent

      * inflate API call results to objects via
      Twitter::API::Trait::InflateObjects

ATTRIBUTES

 consumer_key, consumer_secret

    Required. Every application has it's own application credentials.

 access_token, access_token_secret

    Optional. If provided, every API call will be authenticated with these
    user credentials. See AppAuth for app-only (OAuth2) support, which does
    not require user credentials. You can also pass options -token and
    -token_secret to specify user credentials on each API call.

 api_url

    Optional. Defaults to https://api.twitter.com.

 upload_url

    Optional. Defaults to https://upload.twitter.com.

 api_version

    Optional. Defaults to 1.1.

 agent

    Optional. Used for both the User-Agent and X-Twitter-Client
    identifiers. Defaults to Twitter-API-$VERSION (Perl).

 timeout

    Optional. Request timeout in seconds. Defaults to 10.

METHODS

 get($url, [ \%args ])

    Issues an HTTP GET request to Twitter. If $url is just a path part,
    e.g., account/verify_credentials, it will be expanded to a full URL by
    prepending the api_url, api_version and appending .json. A full URL can
    also be specified, e.g.
    https://api.twitter.com/1.1/account/verify_credentials.json.

    This should accommodate any new API endpoints Twitter adds without
    requiring an update to this module.

 put($url, [ \%args ])

    See get above, for a discussion $url. For file upload, pass an array
    reference as described in
    https://metacpan.org/pod/distribution/HTTP-Message/lib/HTTP/Request/Common.pm#POST-url-Header-Value-...-Content-content.

 get_request_token([ \%args ])

    This is the first step in the OAuth handshake. The only argument
    expected is callback, which defaults to oob for PIN based verification.
    Web applications will pass a callback URL.

    Returns a hashref that includes oauth_token and oauth_token_secret.

    See https://dev.twitter.com/oauth/reference/post/oauth/request_token.

 get_authentication_url(\%args)

    This is the second step in the OAuth handshake. The only required
    argument is oauth_token. Use the value returned by get_request_token.
    Optional arguments: force_login and screen_name to prefill Twitter's
    authentication form.

    See https://dev.twitter.com/oauth/reference/get/oauth/authenticate.

 get_authorization_url(\%args)

    Identical to get_authentication_url, but uses authorization flow,
    rather than authentication flow.

    See https://dev.twitter.com/oauth/reference/get/oauth/authorize.

 get_access_token(\%ags)

    This is the third and final step in the OAuth handshake. Pass the
    request token, request token_secret obtained in the get_request_token
    call, and either the PIN number if you used oob for the callback value
    in get_request_token or the verifier parameter returned in the web
    callback, as verfier.

    See https://dev.twitter.com/oauth/reference/post/oauth/access_token.

 xauth(\%args)

    Requires per application approval from Twitter. Pass username and
    password.

SEE ALSO

      * Net::Twitter - Twitter::API's predecessor (also Net::Twitter::Lite)

      * Mojo::WebService::Twitter - Simple non-blocking Twitter API client

      * API::Twitter - Another simple Twitter API client

AUTHOR

    Marc Mims <marc@questright.com>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2015-2016 by Marc Mims.

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

