README
1NAME
2
3 Twitter::API - A Twitter REST API library for Perl
4
5VERSION
6
7 version 1.0006
8
9SYNOPSIS
10
11 ### Common usage ###
12
13 use Twitter::API;
14 my $client = Twitter::API->new_with_traits(
15 traits => 'Enchilada',
16 consumer_key => $YOUR_CONSUMER_KEY,
17 consumer_secret => $YOUR_CONSUMER_SECRET,
18 access_token => $YOUR_ACCESS_TOKEN,
19 access_token_secret => $YOUR_ACCESS_TOKEN_SECRET,
20 );
21
22 my $me = $client->verify_credentials;
23 my $user = $client->show_user('twitter');
24
25 # In list context, both the Twitter API result and a Twitter::API::Context
26 # object are returned.
27 my ($r, $context) = $client->home_timeline({ count => 200, trim_user => 1 });
28 my $remaning = $context->rate_limit_remaining;
29 my $until = $context->rate_limit_reset;
30
31
32 ### No frills ###
33
34 my $client = Twitter::API->new(
35 consumer_key => $YOUR_CONSUMER_KEY,
36 consumer_secret => $YOUR_CONSUMER_SECRET,
37 );
38
39 my $r = $client->get('account/verify_credentials', {
40 -token => $an_access_token,
41 -token_secret => $an_access_token_secret,
42 });
43
44 ### Error handling ###
45
46 use Twitter::API::Util 'is_twitter_api_error';
47 use Try::Tiny;
48
49 try {
50 my $r = $client->verify_credentials;
51 }
52 catch {
53 die $_ unless is_twitter_api_error($_);
54
55 # The error object includes plenty of information
56 say $_->http_request->as_string;
57 say $_->http_response->as_string;
58 say 'No use retrying right away' if $_->is_permanent_error;
59 if ( $_->is_token_error ) {
60 say "There's something wrong with this token."
61 }
62 if ( $_->twitter_error_code == 326 ) {
63 say "Oops! Twitter thinks you're spam bot!";
64 }
65 };
66
67DESCRIPTION
68
69 Twitter::API provides an interface to the Twitter REST API for perl.
70
71 Features:
72
73 * full support for all Twitter REST API endpoints
74
75 * not dependent on a new distribution for new endpoint support
76
77 * optionally specify access tokens per API call
78
79 * error handling via an exception object that captures the full
80 request/response context
81
82 * full support for OAuth handshake and Xauth authentication
83
84 Additional features are available via optional traits:
85
86 * convenient methods for API endpoints with simplified argument
87 handling via ApiMethods
88
89 * normalized booleans (Twitter likes 'true' and 'false', except when
90 it doesn't) via NormalizeBooleans
91
92 * automatic decoding of HTML entities via DecodeHtmlEntities
93
94 * automatic retry on transient errors via RetryOnError
95
96 * "the whole enchilada" combines all the above traits via Enchilada
97
98 * app-only (OAuth2) support via AppAuth
99
100 * automatic rate limiting via RateLimiting
101
102 Some features are provided by separate distributions to avoid
103 additional dependencies most users won't want or need:
104
105 * async support via subclass Twitter::API::AnyEvent
106 <https://github.com/semifor/Twitter-API-AnyEvent>
107
108 * inflate API call results to objects via
109 Twitter::API::Trait::InflateObjects
110 <https://github.com/semifor/Twitter-API-Trait-InflateObjects>
111
112OVERVIEW
113
114 Migration from Net::Twitter and Net::Twitter::Lite
115
116 Migration support is included to assist users migrating from
117 Net::Twitter and Net::Twitter::Lite. It will be removed from a future
118 release. See Migration for details about migrating your existing
119 Net::Twitter/::Lite applications.
120
121 Normal usage
122
123 Normally, you will construct a Twitter::API client with some traits,
124 primarily ApiMethods. It provides methods for each known Twitter API
125 endpoint. Documentation is provided for each of those methods in
126 ApiMethods.
127
128 See the list of traits in the "DESCRIPTION" and refer to the
129 documentation for each.
130
131 Minimalist usage
132
133 Without any traits, Twitter::API provides access to API endpoints with
134 the get and post methods described below, as well as methods for
135 managing OAuth authentication. API results are simply perl data
136 structures decoded from the JSON responses. Refer to the Twitter API
137 Documentation <https://dev.twitter.com/rest/public> for available
138 endpoints, parameters, and responses.
139
140 Twitter API V2 Beta Support
141
142 Twitter intends to replace the current public API, version 1.1, with
143 version 2.
144
145 See https://developer.twitter.com/en/docs/twitter-api/early-access.
146
147 You can use Twitter::API for the V2 beta with the minimalist usage
148 described just above by passing values in the constructor for
149 api_version and api_ext.
150
151 my $client = Twitter::API->new_with_traits(
152 api_version => '2',
153 api_ext => '',
154 %oauth_credentials,
155 );
156
157 my $user = $client->get("users/by/username/$username");
158
159 More complete V2 support is anticipated in a future release.
160
161ATTRIBUTES
162
163 consumer_key, consumer_secret
164
165 Required. Every application has it's own application credentials.
166
167 access_token, access_token_secret
168
169 Optional. If provided, every API call will be authenticated with these
170 user credentials. See AppAuth for app-only (OAuth2) support, which does
171 not require user credentials. You can also pass options -token and
172 -token_secret to specify user credentials on each API call.
173
174 api_url
175
176 Optional. Defaults to https://api.twitter.com.
177
178 upload_url
179
180 Optional. Defaults to https://upload.twitter.com.
181
182 api_version
183
184 Optional. Defaults to 1.1.
185
186 api_ext
187
188 Optional. Defaults to .json.
189
190 agent
191
192 Optional. Used for both the User-Agent and X-Twitter-Client
193 identifiers. Defaults to Twitter-API-$VERSION (Perl).
194
195 timeout
196
197 Optional. Request timeout in seconds. Defaults to 10.
198
199METHODS
200
201 get($url, [ \%args ])
202
203 Issues an HTTP GET request to Twitter. If $url is just a path part,
204 e.g., account/verify_credentials, it will be expanded to a full URL by
205 prepending the api_url, api_version and appending .json. A full URL can
206 also be specified, e.g.
207 https://api.twitter.com/1.1/account/verify_credentials.json.
208
209 This should accommodate any new API endpoints Twitter adds without
210 requiring an update to this module.
211
212 post($url, [ \%args ])
213
214 See get above, for a discussion $url. For file upload, pass an array
215 reference as described in
216 https://metacpan.org/pod/distribution/HTTP-Message/lib/HTTP/Request/Common.pm#POST-url-Header-Value-...-Content-content.
217
218 oauth_request_token([ \%args ])
219
220 This is the first step in the OAuth handshake. The only argument
221 expected is callback, which defaults to oob for PIN based verification.
222 Web applications will pass a callback URL.
223
224 Returns a hashref that includes oauth_token and oauth_token_secret.
225
226 See
227 https://developer.twitter.com/en/docs/basics/authentication/api-reference/request_token.
228
229 oauth_authentication_url(\%args)
230
231 This is the second step in the OAuth handshake. The only required
232 argument is oauth_token. Use the value returned by get_request_token.
233 Optional arguments: force_login and screen_name to pre-fill Twitter's
234 authentication form.
235
236 See
237 https://developer.twitter.com/en/docs/basics/authentication/api-reference/authenticate.
238
239 oauth_authorization_url(\%args)
240
241 Identical to oauth_authentication_url, but uses authorization flow,
242 rather than authentication flow.
243
244 See
245 https://developer.twitter.com/en/docs/basics/authentication/api-reference/authorize.
246
247 oauth_access_token(\%ags)
248
249 This is the third and final step in the OAuth handshake. Pass the
250 request token, request token_secret obtained in the get_request_token
251 call, and either the PIN number if you used oob for the callback value
252 in get_request_token or the verifier parameter returned in the web
253 callback, as verfier.
254
255 See
256 https://developer.twitter.com/en/docs/basics/authentication/api-reference/access_token.
257
258 xauth(\%args)
259
260 Requires per application approval from Twitter. Pass username and
261 password.
262
263SEE ALSO
264
265 * API::Twitter - Twitter.com API Client
266
267 * AnyEvent::Twitter::Stream - Receive Twitter streaming API in an
268 event loop
269
270 * AnyEvent::Twitter - A thin wrapper for Twitter API using OAuth
271
272 * Mojo::WebService::Twitter - Simple Twitter API client
273
274 * Net::Twitter - Twitter::API's predecessor (also Net::Twitter::Lite)
275
276AUTHOR
277
278 Marc Mims <marc@questright.com>
279
280COPYRIGHT AND LICENSE
281
282 This software is copyright (c) 2015-2021 by Marc Mims.
283
284 This is free software; you can redistribute it and/or modify it under
285 the same terms as the Perl 5 programming language system itself.
286
287