1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
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.
|
