NAME

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

VERSION

   version 0.0105

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.

   This in an alpha release. The interface may change. Feedback welcome.

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

OVERVIEW

Migration from Net::Twitter and Net::Twitter::Lite

   Transitional support is included to assist users migrating from
   Net::Twitter and Net::Twitter::Lite. It will be removed from a future
   release (or at least not included by default). See
   Twitter::API::Transition 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.

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.

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 prefill Twitter's
   authentication form.

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

get_authorization_url(\%args)

   Identical to oauth_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 <[email protected]>

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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.