Twitter::API(3pm)

💖 Twitter::API 💖

okay bestie, sit DOWN, because this is the Perl library that talks to the Twitter REST API and it is genuinely iconic. it's a User Contributed Perl Documentation page, which is giving "written by the community, for the community" ✨

---

🌸 VERSION 🌸

version 1.0006 — yes queen, that's the one 💅

---

✨ SYNOPSIS ✨

okay so here's the whole vibe in code form, no notes:

### 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!";
    }
};

(and yes, $remaning is spelled like that in the original, we do not fix other people's typos in the wild, we simply observe them 🫶)

---

💜 DESCRIPTION 💜

Twitter::API</purpose> provides an interface to the Twitter REST API for perl. that's the whole point. that's the assignment. and it ATE.

Features (the main character list):

• 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 (the little accessories that make the outfit):

• 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 💀 — literally the most Twitter thing ever
• 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 — so they got their own little apartments:

• 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 — so like, don't get attached, bestie. 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. (dramatic, we know.)

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. (manifesting 🙏✨)

---

💅 ATTRIBUTES 💅

🌸 consumer_key, consumer_secret

Required. Every application has it's own application credentials. no key, no vibe. periodt.

🌸 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. (future-proofing, we love to see it 👑)

💖 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. (same energy, different door 🚪)

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. (you cannot just waltz in, you need permission bestie 🫶)

---

🌈 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> — absolute legend, we stan 💜

---

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

---

and that's the whole page, bestie!! 💖 this lil doc shipped with perl v5.32.1 and got stamped 2021-09-11, so go forth and make API calls responsibly, mwah 💅✨