Provided by: libtwitter-api-perl_1.0006-1_all bug

NAME

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

VERSION

       version 1.0006

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 API call

       •   error handling via an exception object that captures the full request/response context

       •   full support for OAuth handshake and Xauth authentication

       Additional features are available 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

       •   automatic rate limiting via RateLimiting

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

       •   async support via subclass Twitter::API::AnyEvent <https://github.com/semifor/Twitter-
           API-AnyEvent>

       •   inflate API call results to objects via Twitter::API::Trait::InflateObjects
           <https://github.com/semifor/Twitter-API-Trait-InflateObjects>

OVERVIEW

   Migration from Net::Twitter and Net::Twitter::Lite
       Migration support is included to assist users migrating from Net::Twitter and
       Net::Twitter::Lite. It will be removed from a future release. See Migration for details
       about migrating your existing Net::Twitter/::Lite applications.

   Normal usage
       Normally, you will construct a Twitter::API client with some traits, primarily ApiMethods.
       It provides methods for each known Twitter API endpoint.  Documentation is provided for
       each of those methods in ApiMethods.

       See the list of traits in the "DESCRIPTION" and refer to the documentation for each.

   Minimalist usage
       Without any traits, Twitter::API provides access to API endpoints with the get and post
       methods described below, as well as methods for managing OAuth authentication. API results
       are simply perl data structures decoded from the JSON responses. Refer to the Twitter API
       Documentation <https://dev.twitter.com/rest/public> for available endpoints, parameters,
       and responses.

   Twitter API V2 Beta Support
       Twitter intends to replace the current public API, version 1.1, with version 2.

       See <https://developer.twitter.com/en/docs/twitter-api/early-access>.

       You can use Twitter::API for the V2 beta with the minimalist usage described just above by
       passing values in the constructor for "api_version" and "api_ext".

           my $client = Twitter::API->new_with_traits(
               api_version => '2',
               api_ext     => '',
               %oauth_credentials,
           );

           my $user = $client->get("users/by/username/$username");

       More complete V2 support is anticipated in a future release.

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.

   api_ext
       Optional. Defaults to ".json".

   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.

   post($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>.

   oauth_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://developer.twitter.com/en/docs/basics/authentication/api-reference/request_token>.

   oauth_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 pre-fill Twitter's authentication form.

       See
       <https://developer.twitter.com/en/docs/basics/authentication/api-reference/authenticate>.

   oauth_authorization_url(\%args)
       Identical to "oauth_authentication_url", but uses authorization flow, rather than
       authentication flow.

       See <https://developer.twitter.com/en/docs/basics/authentication/api-reference/authorize>.

   oauth_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://developer.twitter.com/en/docs/basics/authentication/api-reference/access_token>.

   xauth(\%args)
       Requires per application approval from Twitter. Pass "username" and "password".

SEE ALSO

       •   API::Twitter - Twitter.com API Client

       •   AnyEvent::Twitter::Stream - Receive Twitter streaming API in an event loop

       •   AnyEvent::Twitter - A thin wrapper for Twitter API using OAuth

       •   Mojo::WebService::Twitter - Simple Twitter API client

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

AUTHOR

       Marc Mims <marc@questright.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2015-2021 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.