File Coverage

blib/lib/Net/Twitter/Role/API/REST.pm
Criterion Covered Total %
statement 17 17 100.0
branch n/a
condition n/a
subroutine 6 6 100.0
pod n/a
total 23 23 100.0


line stmt bran cond sub pod time code
1             package Net::Twitter::Role::API::REST;
2             $Net::Twitter::Role::API::REST::VERSION = '4.01042';
3 26     26   30581 use Moose::Role;
  26         53357  
  26         110  
4 26     26   94342 use Carp::Clan qw/^(?:Net::Twitter|Moose|Class::MOP)/;
  26         42  
  26         229  
5 26     26   15077 use Net::Twitter::API;
  26         74  
  26         148  
6 26     26   18695 use DateTime::Format::Strptime;
  26         40  
  26         161  
7 26     26   1430 use URI;
  26         43  
  26         68063  
8              
9             requires qw/ua username password credentials/;
10              
11             with 'Net::Twitter::Role::API::Upload';
12              
13             has apiurl => ( isa => 'Str', is => 'ro', default => 'http://api.twitter.com/1' );
14             has apihost => ( isa => 'Str', is => 'ro', lazy => 1, builder => '_build_apihost' );
15             has apirealm => ( isa => 'Str', is => 'ro', default => 'Twitter API' );
16              
17             sub _build_apihost {
18 2     2   45     my $uri = URI->new(shift->apiurl);
19 2         5652     join ':', $uri->host, $uri->port;
20             }
21              
22             after BUILD => sub {
23                 my $self = shift;
24              
25                 $self->{apiurl} =~ s/^http:/https:/ if $self->ssl;
26             };
27              
28             base_url     'apiurl';
29             authenticate 1;
30              
31             our $DATETIME_PARSER = DateTime::Format::Strptime->new(pattern => '%a %b %d %T %z %Y');
32             datetime_parser $DATETIME_PARSER;
33              
34              
35             twitter_api_method public_timeline => (
36                 description => <<'EOT',
37             Returns the 20 most recent statuses from non-protected users who have
38             set a custom user icon. Does not require authentication. Note that
39             the public timeline is cached for 60 seconds so requesting it more
40             often than that is a waste of resources.
41            
42             If user credentials are provided, C<public_timeline> calls are authenticated,
43             so they count against the authenticated user's rate limit. Use C<<
44             ->public_timeline({ authenticate => 0 }) >> to make an unauthenticated call
45             which will count against the calling IP address' rate limit, instead.
46             EOT
47              
48                 path => 'statuses/public_timeline',
49                 method => 'GET',
50                 returns => 'ArrayRef[Status]',
51                 params => [qw/skip_user trim_user include_entities/],
52                 booleans => [qw/skip_user trim_user include_entities/],
53                 required => [],
54             );
55              
56             twitter_api_method home_timeline => (
57                 description => <<'',
58             Returns the 20 most recent statuses, including retweets, posted by the
59             authenticating user and that user's friends. This is the equivalent of
60             /timeline/home on the Web.
61            
62                 path => 'statuses/home_timeline',
63                 method => 'GET',
64                 params => [qw/since_id max_id count page skip_user exclude_replies contributor_details
65             include_rts include_entities trim_user include_my_retweet/],
66                 booleans => [qw/skip_user exclude_replies contributor_details include_rts include_entities
67             trim_user include_my_retweet/],
68                 required => [],
69                 returns => 'ArrayRef[Status]',
70             );
71              
72             twitter_api_method retweet => (
73                 description => <<'',
74             Retweets a tweet. Requires the id parameter of the tweet you are retweeting.
75             Returns the original tweet with retweet details embedded.
76            
77                 path => 'statuses/retweet/:id',
78                 method => 'POST',
79                 params => [qw/id include_entities trim_user/],
80                 booleans => [qw/include_entities trim_user/],
81                 required => [qw/id/],
82                 returns => 'Status',
83             );
84              
85             twitter_api_method retweets => (
86                 description => <<'',
87             Returns up to 100 of the first retweets of a given tweet.
88            
89                 path => 'statuses/retweets/:id',
90                 method => 'GET',
91                 params => [qw/id count trim_user include_entities/],
92                 booleans => [qw/trim_user include_entities/],
93                 required => [qw/id/],
94                 returns => 'Arrayref[Status]',
95             );
96              
97             twitter_api_method retweeted_by_me => (
98                 description => <<'',
99             Returns the 20 most recent retweets posted by the authenticating user.
100            
101                 path => 'statuses/retweeted_by_me',
102                 method => 'GET',
103                 params => [qw/since_id max_id count page trim_user include_entities/],
104                 booleans => [qw/trim_user include_entities/],
105                 required => [],
106                 returns => 'ArrayRef[Status]',
107             );
108              
109             twitter_api_method retweeted_to_me => (
110                 description => <<'',
111             Returns the 20 most recent retweets posted by the authenticating user's friends.
112            
113                 path => 'statuses/retweeted_to_me',
114                 method => 'GET',
115                 params => [qw/since_id max_id count page/],
116                 required => [],
117                 returns => 'ArrayRef[Status]',
118             );
119              
120             twitter_api_method retweets_of_me => (
121                 description => <<'',
122             Returns the 20 most recent tweets of the authenticated user that have been
123             retweeted by others.
124            
125                 aliases => [qw/retweeted_of_me/],
126                 path => 'statuses/retweets_of_me',
127                 method => 'GET',
128                 params => [qw/since_id max_id count page trim_user include_entities/],
129                 booleans => [qw/trim_user include_entities/],
130                 required => [],
131                 returns => 'ArrayRef[Status]',
132             );
133              
134             twitter_api_method friends_timeline => (
135                 deprecated => 1,
136                 description => <<'',
137             Returns the 20 most recent statuses posted by the authenticating user
138             and that user's friends. This is the equivalent of /home on the Web.
139            
140                 aliases => [qw/following_timeline/],
141                 path => 'statuses/friends_timeline',
142                 method => 'GET',
143                 params => [qw/since_id max_id count page skip_user trim_user include_entities include_rts/],
144                 booleans => [qw/skip_user trim_user include_entities include_rts/],
145                 required => [],
146                 returns => 'ArrayRef[Status]',
147             );
148              
149             twitter_api_method user_timeline => (
150                 description => <<'',
151             Returns the 20 most recent statuses posted from the authenticating
152             user. It's also possible to request another user's timeline via the id
153             parameter. This is the equivalent of the Web /archive page for
154             your own user, or the profile page for a third party.
155            
156                 path => 'statuses/user_timeline/:id',
157                 method => 'GET',
158                 params => [qw/id user_id screen_name since_id max_id count page skip_user trim_user include_entities include_rts/],
159                 booleans => [qw/skip_user trim_user include_entities include_rts/],
160                 required => [],
161                 returns => 'ArrayRef[Status]',
162             );
163              
164             # TODO: URL should be 'mentions', not 'replies', but the Laconica API doesn't
165             # recognize 'mentions' yet, so we'll cheat, as long as Twitter plays along and
166             # keeps 'replies' active or until Laconica/Identica is fixed.
167             # (Fixed in Laconi.ca 0.7.4.)
168             twitter_api_method mentions => (
169                 description => <<'',
170             Returns the 20 most recent mentions (statuses containing @username) for the
171             authenticating user.
172            
173                 aliases => [qw/replies/],
174                 path => 'statuses/mentions',
175                 method => 'GET',
176                 params => [qw/since_id max_id count page trim_user include_rts include_entities/],
177                 booleans => [qw/trim_user include_rts include_entities/],
178                 required => [],
179                 returns => 'ArrayRef[Status]',
180             );
181              
182             twitter_api_method show_status => (
183                 description => <<'',
184             Returns a single status, specified by the id parameter. The
185             status's author will be returned inline.
186            
187                 path => 'statuses/show/:id',
188                 method => 'GET',
189                 params => [qw/id trim_user include_entities/],
190                 booleans => [qw/trim_user include_entities/],
191                 required => [qw/id/],
192                 returns => 'Status',
193             );
194              
195             twitter_api_method update => (
196                 path => 'statuses/update',
197                 method => 'POST',
198                 params => [qw/status lat long place_id display_coordinates in_reply_to_status_id trim_user include_entities/],
199                 required => [qw/status/],
200                 booleans => [qw/display_coordinates trim_user include_entities/],
201                 add_source => 1,
202                 returns => 'Status',
203                 description => <<'EOT',
204            
205             Updates the authenticating user's status. Requires the status parameter
206             specified. A status update with text identical to the authenticating
207             user's current status will be ignored.
208            
209             =over 4
210            
211             =item status
212            
213             Required. The text of your status update. URL encode as necessary. Statuses
214             over 140 characters will cause a 403 error to be returned from the API.
215            
216             =item in_reply_to_status_id
217            
218             Optional. The ID of an existing status that the update is in reply to. o Note:
219             This parameter will be ignored unless the author of the tweet this parameter
220             references is mentioned within the status text. Therefore, you must include
221             @username, where username is the author of the referenced tweet, within the
222             update.
223            
224             =item lat
225            
226             Optional. The location's latitude that this tweet refers to. The valid ranges
227             for latitude is -90.0 to +90.0 (North is positive) inclusive. This parameter
228             will be ignored if outside that range, if it is not a number, if geo_enabled is
229             disabled, or if there not a corresponding long parameter with this tweet.
230            
231             =item long
232            
233             Optional. The location's longitude that this tweet refers to. The valid ranges
234             for longitude is -180.0 to +180.0 (East is positive) inclusive. This parameter
235             will be ignored if outside that range, if it is not a number, if geo_enabled is
236             disabled, or if there not a corresponding lat parameter with this tweet.
237            
238             =item place_id
239            
240             Optional. The place to attach to this status update. Valid place_ids can be
241             found by querying C<reverse_geocode>.
242            
243             =item display_coordinates
244            
245             Optional. By default, geo-tweets will have their coordinates exposed in the
246             status object (to remain backwards compatible with existing API applications).
247             To turn off the display of the precise latitude and longitude (but keep the
248             contextual location information), pass C<display_coordinates => 0> on the
249             status update.
250            
251             =back
252            
253             EOT
254              
255             );
256              
257             twitter_api_method destroy_status => (
258                 description => <<'',
259             Destroys the status specified by the required ID parameter. The
260             authenticating user must be the author of the specified status.
261            
262                 path => 'statuses/destroy/:id',
263                 method => 'POST',
264                 params => [qw/id trim_user include_entities/],
265                 booleans => [qw/trim_user include_entities/],
266                 required => [qw/id/],
267                 returns => 'Status',
268             );
269              
270             twitter_api_method friends => (
271                 deprecated => 1,
272                 description => <<'EOT',
273             This method has been deprecated. Twitter intends to stop support for it on May
274             14, 2012. Use C<friends_ids> and C<lookup_users> instead.
275            
276             Returns a reference to an array of the user's friends. If C<id>, C<user_id>,
277             or C<screen_name> is not specified, the friends of the authenticating user are
278             returned. The returned users are ordered from most recently followed to least
279             recently followed.
280            
281             Use the optional C<cursor> parameter to retrieve users in pages of 100. When
282             the C<cursor> parameter is used, the return value is a reference to a hash with
283             keys C<previous_cursor>, C<next_cursor>, and C<users>. The value of C<users>
284             is a reference to an array of the user's friends. The result set isn't
285             guaranteed to be 100 every time as suspended users will be filtered out. Set
286             the optional C<cursor> parameter to -1 to get the first page of users. Set it
287             to the prior return's value of C<previous_cursor> or C<next_cursor> to page
288             forward or backwards. When there are no prior pages, the value of
289             C<previous_cursor> will be 0. When there are no subsequent pages, the value of
290             C<next_cursor> will be 0.
291             EOT
292              
293                 aliases => [qw/following/],
294                 path => 'statuses/friends/:id',
295                 method => 'GET',
296                 params => [qw/id user_id screen_name cursor include_entities/],
297                 booleans => [qw/include_entities/],
298                 required => [qw//],
299                 returns => 'Hashref|ArrayRef[User]',
300             );
301              
302             twitter_api_method followers => (
303                 deprecated => 1,
304                 description => <<'EOT',
305             This method has been deprecated. Twitter intends to stop support for it on May
306             14, 2012. Use C<friends_ids> and C<lookup_users> instead.
307            
308             Returns a reference to an array of the user's followers. If C<id>, C<user_id>,
309             or C<screen_name> is not specified, the followers of the authenticating user are
310             returned. The returned users are ordered from most recently followed to least
311             recently followed.
312            
313             Use the optional C<cursor> parameter to retrieve users in pages of 100. When
314             the C<cursor> parameter is used, the return value is a reference to a hash with
315             keys C<previous_cursor>, C<next_cursor>, and C<users>. The value of C<users>
316             is a reference to an array of the user's friends. The result set isn't
317             guaranteed to be 100 every time as suspended users will be filtered out. Set
318             the optional C<cursor> parameter to -1 to get the first page of users. Set it
319             to the prior return's value of C<previous_cursor> or C<next_cursor> to page
320             forward or backwards. When there are no prior pages, the value of
321             C<previous_cursor> will be 0. When there are no subsequent pages, the value of
322             C<next_cursor> will be 0.
323             EOT
324              
325                 path => 'statuses/followers/:id',
326                 method => 'GET',
327                 params => [qw/id user_id screen_name cursor include_entities/],
328                 booleans => [qw/include_entities/],
329                 required => [qw//],
330                 returns => 'HashRef|ArrayRef[User]',
331             );
332              
333             twitter_api_method show_user => (
334                 description => <<'',
335             Returns extended information of a given user, specified by ID or screen
336             name as per the required id parameter. This information includes
337             design settings, so third party developers can theme their widgets
338             according to a given user's preferences. You must be properly
339             authenticated to request the page of a protected user.
340            
341                 path => 'users/show/:id',
342                 method => 'GET',
343                 params => [qw/id screen_name include_entities/],
344                 booleans => [qw/include_entities/],
345                 required => [qw/id/],
346                 returns => 'ExtendedUser',
347             );
348              
349             twitter_api_method contributees => (
350                 path => 'users/contributees',
351                 method => 'GET',
352                 params => [qw/user_id screen_name include_entities skip_satus/],
353                 required => [],
354                 booleans => [qw/include_entities skip_satus/],
355                 returns => 'ArrayRef[User]',
356                 description => <<'',
357             Returns an array of users that the specified user can contribute to.
358            
359             );
360              
361             twitter_api_method contributors => (
362                 path => 'users/contributors',
363                 method => 'GET',
364                 params => [qw/user_id screen_name include_entities skip_satus/],
365                 required => [],
366                 booleans => [qw/include_entities skip_satus/],
367                 returns => 'ArrayRef[User]',
368                 description => <<'',
369             Returns an array of users who can contribute to the specified account.
370            
371             );
372              
373             twitter_api_method direct_messages => (
374                 description => <<'',
375             Returns a list of the 20 most recent direct messages sent to the authenticating
376             user including detailed information about the sending and recipient users.
377            
378                 path => 'direct_messages',
379                 method => 'GET',
380                 params => [qw/since_id max_id count page include_entities/],
381                 required => [qw/include_entities/],
382                 returns => 'ArrayRef[DirectMessage]',
383             );
384              
385             twitter_api_method sent_direct_messages => (
386                 description => <<'',
387             Returns a list of the 20 most recent direct messages sent by the authenticating
388             user including detailed information about the sending and recipient users.
389            
390                 path => 'direct_messages/sent',
391                 method => 'GET',
392                 params => [qw/since_id max_id page count include_entities/],
393                 booleans => [qw/include_entities/],
394                 required => [qw//],
395                 returns => 'ArrayRef[DirectMessage]',
396             );
397              
398             twitter_api_method new_direct_message => (
399                 description => <<'',
400             Sends a new direct message to the specified user from the authenticating user.
401             Requires both the user and text parameters. Returns the sent message when
402             successful. In order to support numeric screen names, the C<screen_name> or
403             C<user_id> parameters may be used instead of C<user>.
404            
405                 path => 'direct_messages/new',
406                 method => 'POST',
407                 params => [qw/user text screen_name user_id include_entities/],
408                 booleans => [qw/include_entities/],
409                 required => [qw/user text/],
410                 returns => 'DirectMessage',
411             );
412              
413             twitter_api_method destroy_direct_message => (
414                 description => <<'',
415             Destroys the direct message specified in the required ID parameter.
416             The authenticating user must be the recipient of the specified direct
417             message.
418            
419                 path => 'direct_messages/destroy/:id',
420                 method => 'POST',
421                 params => [qw/id include_entities/],
422                 booleans => [qw/include_entities/],
423                 required => [qw/id/],
424                 returns => 'DirectMessage',
425             );
426              
427             twitter_api_method show_friendship => (
428                 description => <<'',
429             Returns detailed information about the relationship between two users.
430            
431                 aliases => [qw/show_relationship/],
432                 path => 'friendships/show',
433                 method => 'GET',
434                 params => [qw/source_id source_screen_name target_id target_id_name/],
435                 required => [qw/id/],
436                 returns => 'Relationship',
437             );
438              
439             twitter_api_method create_friend => (
440                 description => <<'',
441             Befriends the user specified in the ID parameter as the authenticating user.
442             Returns the befriended user when successful. Returns a string describing the
443             failure condition when unsuccessful.
444            
445                 aliases => [qw/follow_new/],
446                 path => 'friendships/create/:id',
447                 method => 'POST',
448                 params => [qw/id user_id screen_name follow include_entities/],
449                 booleans => [qw/include_entities follow/],
450                 required => [qw/id/],
451                 returns => 'BasicUser',
452             );
453              
454             twitter_api_method destroy_friend => (
455                 description => <<'',
456             Discontinues friendship with the user specified in the ID parameter as the
457             authenticating user. Returns the un-friended user when successful.
458             Returns a string describing the failure condition when unsuccessful.
459            
460                 aliases => [qw/unfollow/],
461                 path => 'friendships/destroy/:id',
462                 method => 'POST',
463                 params => [qw/id user_id screen_name include_entities/],
464                 booleans => [qw/include_entities/],
465                 required => [qw/id/],
466                 returns => 'BasicUser',
467             );
468              
469             twitter_api_method friendship_exists => (
470                 aliases => [qw/relationship_exists follows/], # Net::Twitter
471                 description => <<'EOT',
472             Tests for the existence of friendship between two users. Will return true if
473             user_a follows user_b, otherwise will return false.
474            
475             Use of C<user_a> and C<user_b> is deprecated. It has been preserved for backwards
476             compatibility, and is used for the two-argument positional form:
477            
478             $nt->friendship_exists($user_a, $user_b);
479            
480             Instead, you should use one of the named argument forms:
481            
482             $nt->friendship_exists({ user_id_a => $id1, user_id_b => $id2 });
483             $nt->friendship_exists({ screen_name_a => $name1, screen_name_b => $name2 });
484            
485             Consider using C<show_friendship> instead.
486             EOT
487              
488                 path => 'friendships/exists',
489                 method => 'GET',
490                 params => [qw/user_id_a user_id_b screen_name_a screen_name_b user_a user_b/],
491                 required => [qw/user_a user_b/],
492                 returns => 'Bool',
493             );
494              
495             twitter_api_method no_retweet_ids => (
496                 description => <<'',
497             Returns an ARRAY ref of user IDs for which the authenticating user does not
498             want to receive retweets.
499            
500                 path => 'friendships/no_retweet_ids',
501                 method => 'GET',
502                 params => [],
503                 required => [],
504                 returns => 'ArrayRef[UserIDs]',
505             );
506              
507             twitter_api_method friends_ids => (
508                 description => <<'EOT',
509             Returns a reference to an array of numeric IDs for every user followed by the
510             specified user. The order of the IDs is reverse chronological.
511            
512             Use the optional C<cursor> parameter to retrieve IDs in pages of 5000. When
513             the C<cursor> parameter is used, the return value is a reference to a hash with
514             keys C<previous_cursor>, C<next_cursor>, and C<ids>. The value of C<ids> is a
515             reference to an array of IDS of the user's friends. Set the optional C<cursor>
516             parameter to -1 to get the first page of IDs. Set it to the prior return's
517             value of C<previous_cursor> or C<next_cursor> to page forward or backwards.
518             When there are no prior pages, the value of C<previous_cursor> will be 0. When
519             there are no subsequent pages, the value of C<next_cursor> will be 0.
520             EOT
521              
522                 aliases => [qw/following_ids/],
523                 path => 'friends/ids/:id',
524                 method => 'GET',
525                 params => [qw/id user_id screen_name cursor/],
526                 required => [qw/id/],
527                 returns => 'HashRef|ArrayRef[Int]',
528             );
529              
530             twitter_api_method followers_ids => (
531                 description => <<'EOT',
532             Returns a reference to an array of numeric IDs for every user following the
533             specified user. The order of the IDs may change from call to call. To obtain
534             the screen names, pass the arrayref to L</lookup_users>.
535            
536             Use the optional C<cursor> parameter to retrieve IDs in pages of 5000. When
537             the C<cursor> parameter is used, the return value is a reference to a hash with
538             keys C<previous_cursor>, C<next_cursor>, and C<ids>. The value of C<ids> is a
539             reference to an array of IDS of the user's followers. Set the optional C<cursor>
540             parameter to -1 to get the first page of IDs. Set it to the prior return's
541             value of C<previous_cursor> or C<next_cursor> to page forward or backwards.
542             When there are no prior pages, the value of C<previous_cursor> will be 0. When
543             there are no subsequent pages, the value of C<next_cursor> will be 0.
544             EOT
545              
546                 path => 'followers/ids/:id',
547                 method => 'GET',
548                 params => [qw/id user_id screen_name cursor/],
549                 required => [qw/id/],
550                 returns => 'HashRef|ArrayRef[Int]',
551             );
552              
553             twitter_api_method verify_credentials => (
554                 description => <<'',
555             Returns an HTTP 200 OK response code and a representation of the
556             requesting user if authentication was successful; returns a 401 status
557             code and an error message if not. Use this method to test if supplied
558             user credentials are valid.
559            
560                 path => 'account/verify_credentials',
561                 method => 'GET',
562                 params => [qw/include_entities/],
563                 booleans => [qw/include_entities/],
564                 required => [qw//],
565                 returns => 'ExtendedUser',
566             );
567              
568             twitter_api_method end_session => (
569                 description => <<'',
570             Ends the session of the authenticating user, returning a null cookie.
571             Use this method to sign users out of client-facing applications like
572             widgets.
573            
574                 path => 'account/end_session',
575                 method => 'POST',
576                 params => [qw//],
577                 required => [qw//],
578                 returns => 'Error', # HTTP Status: 200, error content. Silly!
579             );
580              
581             twitter_api_method update_location => (
582                 description => <<'',
583             This method has been deprecated in favor of the update_profile method.
584             Its URL will continue to work, but please consider migrating to the newer
585             and more comprehensive method of updating profile attributes.
586            
587                 deprecated => 1,
588                 path => 'account/update_location',
589                 method => 'POST',
590                 params => [qw/location/],
591                 required => [qw/location/],
592                 returns => 'BasicUser',
593             );
594              
595             twitter_api_method update_delivery_device => (
596                 description => <<'',
597             Sets which device Twitter delivers updates to for the authenticating
598             user. Sending none as the device parameter will disable IM or SMS
599             updates.
600            
601                 path => 'account/update_delivery_device',
602                 method => 'POST',
603                 params => [qw/device/],
604                 required => [qw/device/],
605                 returns => 'BasicUser',
606             );
607              
608             twitter_api_method update_profile_colors => (
609                 description => <<'',
610             Sets one or more hex values that control the color scheme of the
611             authenticating user's profile page on twitter.com. These values are
612             also returned in the /users/show API method.
613            
614                 path => 'account/update_profile_colors',
615                 method => 'POST',
616                 params => [qw/
617             profile_background_color
618             profile_text_color
619             profile_link_color
620             profile_sidebar_fill_color
621             profile_sidebar_border_color
622             /],
623                 required => [qw//],
624                 returns => 'ExtendedUser',
625             );
626              
627             twitter_api_method update_profile_image => (
628                 description => <<'EOT',
629             Updates the authenticating user's profile image. The C<image> parameter is an
630             arrayref with the following interpretation:
631            
632             [ $file ]
633             [ $file, $filename ]
634             [ $file, $filename, Content_Type => $mime_type ]
635             [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ]
636            
637             The first value of the array (C<$file>) is the name of a file to open. The
638             second value (C<$filename>) is the name given to Twitter for the file. If
639             C<$filename> is not provided, the basename portion of C<$file> is used. If
640             C<$mime_type> is not provided, it will be provided automatically using
641             L<LWP::MediaTypes::guess_media_type()>.
642            
643             C<$raw_image_data> can be provided, rather than opening a file, by passing
644             C<undef> as the first array value.
645             EOT
646              
647                 path => 'account/update_profile_image',
648                 method => 'POST',
649                 params => [qw/image/],
650                 required => [qw/image/],
651                 returns => 'ExtendedUser',
652             );
653              
654             twitter_api_method update_profile_background_image => (
655                 description => <<'',
656             Updates the authenticating user's profile background image. The C<image>
657             parameter must be an arrayref with the same interpretation as the C<image>
658             parameter in the C<update_profile_image> method. The C<use> parameter allows
659             you to specify whether to use the uploaded profile background or not. See
660             that method's documentation for details.
661            
662                 path => 'account/update_profile_background_image',
663                 method => 'POST',
664                 params => [qw/image use/],
665                 required => [qw/image/],
666                 booleans => [qw/use/],
667                 returns => 'ExtendedUser',
668             );
669              
670             twitter_api_method rate_limit_status => (
671                 description => <<'EOT',
672             Returns the remaining number of API requests available to the
673             authenticated user before the API limit is reached for the current hour.
674            
675             Use C<< ->rate_limit_status({ authenticate => 0 }) >> to force an
676             unauthenticated call, which will return the status for the IP address rather
677             than the authenticated user. (Note: for a web application, this is the server's
678             IP address.)
679             EOT
680              
681                 path => 'account/rate_limit_status',
682                 method => 'GET',
683                 params => [qw//],
684                 required => [qw//],
685                 returns => 'RateLimitStatus',
686             );
687              
688             twitter_api_method update_profile => (
689                 description => <<'',
690             Sets values that users are able to set under the "Account" tab of their
691             settings page. Only the parameters specified will be updated; to only
692             update the "name" attribute, for example, only include that parameter
693             in your request.
694            
695                 path => 'account/update_profile',
696                 method => 'POST',
697                 params => [qw/ name email url location description include_entities/],
698                 booleans => [qw/include_entities/],
699                 required => [qw//],
700                 returns => 'ExtendedUser',
701             );
702              
703             twitter_api_method favorites => (
704                 description => <<'',
705             Returns the 20 most recent favorite statuses for the authenticating
706             user or user specified by the ID parameter.
707            
708                 path => 'favorites/:id',
709                 method => 'GET',
710                 params => [qw/id page include_entities/],
711                 booleans => [qw/include_entities/],
712                 required => [qw//],
713                 returns => 'ArrayRef[Status]',
714             );
715              
716             twitter_api_method create_favorite => (
717                 description => <<'',
718             Favorites the status specified in the ID parameter as the
719             authenticating user. Returns the favorite status when successful.
720            
721                 path => 'favorites/create/:id',
722                 method => 'POST',
723                 params => [qw/id include_entities/],
724                 booleans => [qw/include_entities/],
725                 required => [qw/id/],
726                 returns => 'Status',
727             );
728              
729             twitter_api_method destroy_favorite => (
730                 description => <<'',
731             Un-favorites the status specified in the ID parameter as the
732             authenticating user. Returns the un-favorited status.
733            
734                 path => 'favorites/destroy/:id',
735                 method => 'POST',
736                 params => [qw/id include_entities/],
737                 booleans => [qw/include_entities/],
738                 required => [qw/id/],
739                 returns => 'Status',
740             );
741              
742             twitter_api_method enable_notifications => (
743                 description => <<'',
744             Enables notifications for updates from the specified user to the
745             authenticating user. Returns the specified user when successful.
746            
747                 path => 'notifications/follow/:id',
748                 method => 'POST',
749                 params => [qw/id screen_name include_entities/],
750                 booleans => [qw/include_entities/],
751                 required => [qw/id/],
752                 returns => 'BasicUser',
753             );
754              
755             twitter_api_method disable_notifications => (
756                 description => <<'',
757             Disables notifications for updates from the specified user to the
758             authenticating user. Returns the specified user when successful.
759            
760                 path => 'notifications/leave/:id',
761                 method => 'POST',
762                 params => [qw/id screen_name include_entities/],
763                 booleans => [qw/include_entities/],
764                 required => [qw/id/],
765                 returns => 'BasicUser',
766             );
767              
768             twitter_api_method create_block => (
769                 description => <<'',
770             Blocks the user specified in the ID parameter as the authenticating user.
771             Returns the blocked user when successful. You can find out more about
772             blocking in the Twitter Support Knowledge Base.
773            
774                 path => 'blocks/create/:id',
775                 method => 'POST',
776                 params => [qw/id user_id screen_name include_entities/],
777                 booleans => [qw/include_entities/],
778                 required => [qw/id/],
779                 returns => 'BasicUser',
780             );
781              
782              
783             twitter_api_method destroy_block => (
784                 description => <<'',
785             Un-blocks the user specified in the ID parameter as the authenticating user.
786             Returns the un-blocked user when successful.
787            
788                 path => 'blocks/destroy/:id',
789                 method => 'POST',
790                 params => [qw/id user_id screen_name/],
791                 booleans => [qw/include_entities/],
792                 required => [qw/id/],
793                 returns => 'BasicUser',
794             );
795              
796              
797             twitter_api_method block_exists => (
798                 description => <<'',
799             Returns if the authenticating user is blocking a target user. Will return the blocked user's
800             object if a block exists, and error with HTTP 404 response code otherwise.
801            
802                 path => 'blocks/exists/:id',
803                 method => 'GET',
804                 params => [qw/id user_id screen_name include_entities/],
805                 booleans => [qw/include_entities/],
806                 required => [qw/id/],
807                 returns => 'BasicUser',
808             );
809              
810              
811             twitter_api_method blocking => (
812                 description => <<'',
813             Returns an array of user objects that the authenticating user is blocking.
814            
815                 path => 'blocks/blocking',
816                 method => 'GET',
817                 params => [qw/page include_entities/],
818                 booleans => [qw/include_entities/],
819                 required => [qw//],
820                 returns => 'ArrayRef[BasicUser]',
821             );
822              
823              
824             twitter_api_method blocking_ids => (
825                 description => <<'',
826             Returns an array of numeric user ids the authenticating user is blocking.
827            
828                 path => 'blocks/blocking/ids',
829                 method => 'GET',
830                 params => [qw//],
831                 required => [qw//],
832                 returns => 'ArrayRef[Int]',
833             );
834              
835             twitter_api_method test => (
836                 description => <<'',
837             Returns the string "ok" status code.
838            
839                 path => 'help/test',
840                 method => 'GET',
841                 params => [qw//],
842                 required => [qw//],
843                 returns => 'Str',
844             );
845              
846             twitter_api_method downtime_schedule => (
847                 description => <<'',
848             Returns the same text displayed on L<http://twitter.com/home> when a
849             maintenance window is scheduled.
850            
851                 deprecated => 1,
852                 path => 'help/downtime_schedule',
853                 method => 'GET',
854                 params => [qw//],
855                 required => [qw//],
856                 returns => 'Str',
857             );
858              
859             twitter_api_method get_configuration => (
860                 path => 'help/configuration',
861                 method => 'GET',
862                 params => [],
863                 required => [],
864                 returns => 'HashRef',
865                 description => <<'EOT',
866             Returns the current configuration used by Twitter including twitter.com slugs
867             which are not usernames, maximum photo resolutions, and t.co URL lengths.
868            
869             It is recommended applications request this endpoint when they are loaded, but
870             no more than once a day.
871             EOT
872              
873             );
874              
875             twitter_api_method get_languages => (
876                 path => 'help/languages',
877                 method => 'GET',
878                 params => [],
879                 required => [],
880                 returns => 'ArrayRef[Lanugage]',
881                 description => <<'',
882             Returns the list of languages supported by Twitter along with their ISO 639-1
883             code. The ISO 639-1 code is the two letter value to use if you include lang
884             with any of your requests.
885            
886             );
887              
888             twitter_api_method saved_searches => (
889                 description => <<'',
890             Returns the authenticated user's saved search queries.
891            
892                 path => 'saved_searches',
893                 method => 'GET',
894                 params => [],
895                 required => [],
896                 returns => 'ArrayRef[SavedSearch]',
897             );
898              
899             twitter_api_method show_saved_search => (
900                 description => <<'',
901             Retrieve the data for a saved search, by C<id>, owned by the authenticating user.
902            
903                 path => 'saved_searches/show/:id',
904                 method => 'GET',
905                 params => [qw/id/],
906                 required => [qw/id/],
907                 returns => 'SavedSearch',
908             );
909              
910             twitter_api_method create_saved_search => (
911                 description => <<'',
912             Creates a saved search for the authenticated user.
913            
914                 path => 'saved_searches/create',
915                 method => 'POST',
916                 params => [qw/query/],
917                 required => [qw/query/],
918                 returns => 'SavedSearch',
919             );
920              
921             twitter_api_method destroy_saved_search => (
922                 description => <<'',
923             Destroys a saved search. The search, specified by C<id>, must be owned
924             by the authenticating user.
925            
926                 path => 'saved_searches/destroy/:id',
927                 method => 'POST',
928                 params => [qw/id/],
929                 required => [qw/id/],
930                 returns => 'SavedSearch',
931             );
932              
933             twitter_api_method report_spam => (
934                 description => <<'',
935             The user specified in the id is blocked by the authenticated user and reported as a spammer.
936            
937                 path => 'report_spam',
938                 method => 'POST',
939                 params => [qw/id user_id screen_name include_entities/],
940                 booleans => [qw/include_entities/],
941                 required => [qw/id/],
942                 returns => 'User',
943             );
944              
945             twitter_api_method users_search => (
946                 aliases => [qw/find_people search_users/],
947                 path => 'users/search',
948                 method => 'GET',
949                 params => [qw/q per_page page include_entities/],
950                 booleans => [qw/include_entities/],
951                 required => [qw/q/],
952                 returns => 'ArrayRef[Users]',
953                 description => <<'',
954             Run a search for users similar to Find People button on Twitter.com; the same
955             results returned by people search on Twitter.com will be returned by using this
956             API (about being listed in the People Search). It is only possible to retrieve
957             the first 1000 matches from this API.
958            
959             );
960              
961             twitter_api_method trends_available => (
962                 path => 'trends/available',
963                 method => 'GET',
964                 params => [qw/lat long/],
965                 required => [],
966                 authenticate => 0,
967                 returns => 'ArrayRef[Location]',
968                 description => <<EOT,
969             Returns the locations with trending topic information. The response is an
970             array of "locations" that encode the location's WOEID (a Yahoo! Where On Earth
971             ID L<http://developer.yahoo.com/geo/geoplanet/>) and some other human-readable
972             information such as a the location's canonical name and country.
973            
974             When the optional C<lat> and C<long> parameters are passed, the available trend
975             locations are sorted by distance from that location, nearest to farthest.
976            
977             Use the WOEID returned in the location object to query trends for a specific
978             location.
979             EOT
980             );
981              
982             twitter_api_method trends_location => (
983                 path => 'trends/:woeid',
984                 method => 'GET',
985                 params => [qw/woeid/],
986                 required => [qw/woeid/],
987                 returns => 'ArrayRef[Trend]',
988                 authenticate => 0,
989                 description => <<'',
990             Returns the top 10 trending topics for a specific location. The response is an
991             array of "trend" objects that encode the name of the trending topic, the query
992             parameter that can be used to search for the topic on Search, and the direct
993             URL that can be issued against Search. This information is cached for five
994             minutes, and therefore users are discouraged from querying these endpoints
995             faster than once every five minutes. Global trends information is also
996             available from this API by using a WOEID of 1.
997            
998             );
999              
1000             twitter_api_method trends => (
1001                 description => <<'',
1002             Returns the top ten queries that are currently trending on Twitter. The
1003             response includes the time of the request, the name of each trending topic, and
1004             the url to the Twitter Search results page for that topic.
1005            
1006                 path => 'trends',
1007                 method => 'GET',
1008                 params => [qw//],
1009                 required => [qw//],
1010                 authenticate => 0,
1011                 returns => 'ArrayRef[Query]',
1012                 deprecated => 1,
1013             );
1014              
1015             my $trends_deprecation_warned = 0;
1016             around trends => sub {
1017                 my $orig = shift;
1018                 my $self = shift;
1019              
1020                 my $args = ref $_[-1] eq ref {} ? pop : {};
1021              
1022                 $trends_deprecation_warned ||= do {
1023                     local $Carp::CarpLevel = 3;
1024                     carp "The 'trends' API method has been deprecated; instead, use trends_location({ woeid => 1 })";
1025                     1;
1026                 };
1027              
1028                 $args->{woeid} = 1;
1029              
1030                 return $self->trends_location(@_, $args);
1031             };
1032              
1033             twitter_api_method trends_current => (
1034                 description => <<'',
1035             Returns the current top ten trending topics on Twitter. The response includes
1036             the time of the request, the name of each trending topic, and query used on
1037             Twitter Search results page for that topic.
1038            
1039                 path => 'trends/current',
1040                 method => 'GET',
1041                 params => [qw/exclude/],
1042                 required => [qw//],
1043                 authenticate => 0,
1044                 returns => 'HashRef',
1045             );
1046              
1047             twitter_api_method trends_daily => (
1048                 description => <<'',
1049             Returns the top 20 trending topics for each hour in a given day.
1050            
1051                 path => 'trends/daily',
1052                 method => 'GET',
1053                 params => [qw/date exclude/],
1054                 required => [qw//],
1055                 authenticate => 0,
1056                 returns => 'HashRef',
1057             );
1058              
1059             twitter_api_method trends_weekly => (
1060                 description => <<'',
1061             Returns the top 30 trending topics for each day in a given week.
1062            
1063                 path => 'trends/weekly',
1064                 method => 'GET',
1065                 params => [qw/date exclude/],
1066                 required => [qw//],
1067                 authenticate => 0,
1068                 returns => 'HashRef',
1069             );
1070              
1071             twitter_api_method reverse_geocode => (
1072                 path => 'geo/reverse_geocode',
1073                 method => 'GET',
1074                 params => [qw/lat long accuracy granularity max_results/],
1075                 required => [qw/lat long/],
1076                 returns => 'HashRef',
1077                 description => <<'EOT',
1078            
1079             Search for places (cities and neighborhoods) that can be attached to a
1080             statuses/update. Given a latitude and a longitude, return a list of all the
1081             valid places that can be used as a place_id when updating a status.
1082             Conceptually, a query can be made from the user's location, retrieve a list of
1083             places, have the user validate the location he or she is at, and then send the
1084             ID of this location up with a call to statuses/update.
1085            
1086             There are multiple granularities of places that can be returned --
1087             "neighborhoods", "cities", etc. At this time, only United States data is
1088             available through this method.
1089            
1090             =over 4
1091            
1092             =item lat
1093            
1094             Required. The latitude to query about. Valid ranges are -90.0 to +90.0 (North
1095             is positive) inclusive.
1096            
1097             =item long
1098            
1099             Required. The longitude to query about. Valid ranges are -180.0 to +180.0
1100             (East is positive) inclusive.
1101            
1102             =item accuracy
1103            
1104             Optional. A hint on the "region" in which to search. If a number, then this is
1105             a radius in meters, but it can also take a string that is suffixed with ft to
1106             specify feet. If this is not passed in, then it is assumed to be 0m. If
1107             coming from a device, in practice, this value is whatever accuracy the device
1108             has measuring its location (whether it be coming from a GPS, WiFi
1109             triangulation, etc.).
1110            
1111             =item granularity
1112            
1113             Optional. The minimal granularity of data to return. If this is not passed
1114             in, then C<neighborhood> is assumed. C<city> can also be passed.
1115            
1116             =item max_results
1117            
1118             Optional. A hint as to the number of results to return. This does not
1119             guarantee that the number of results returned will equal max_results, but
1120             instead informs how many "nearby" results to return. Ideally, only pass in the
1121             number of places you intend to display to the user here.
1122            
1123             =back
1124            
1125             EOT
1126             );
1127              
1128             twitter_api_method geo_id => (
1129                 path => 'geo/id/:id',
1130                 method => 'GET',
1131                 params => [qw/id/],
1132                 required => [qw/id/],
1133                 returns => 'HashRef',
1134                 description => <<'EOT',
1135             Returns details of a place returned from the C<reverse_geocode> method.
1136             EOT
1137             );
1138              
1139             twitter_api_method geo_search => (
1140                 path => 'geo/search',
1141                 method => 'GET',
1142                 params => [qw/
1143             lat long query ip granularity accuracy max_results
1144             contained_within attribute:street_address callback
1145             /],
1146                 required => [],
1147                 returns => 'HashRef',
1148                 description => <<'EOT',
1149             Search for places that can be attached to a statuses/update. Given a latitude
1150             and a longitude pair, an IP address, or a name, this request will return a list
1151             of all the valid places that can be used as the place_id when updating a
1152             status.
1153            
1154             Conceptually, a query can be made from the user's location, retrieve a list of
1155             places, have the user validate the location he or she is at, and then send the
1156             ID of this location with a call to statuses/update.
1157            
1158             This is the recommended method to use find places that can be attached to
1159             statuses/update. Unlike geo/reverse_geocode which provides raw data access,
1160             this endpoint can potentially re-order places with regards to the user who
1161             is authenticated. This approach is also preferred for interactive place
1162             matching with the user.
1163             EOT
1164              
1165             );
1166              
1167             twitter_api_method similar_places => (
1168                 path => 'geo/similar_places',
1169                 method => 'GET',
1170                 params => [qw/lat long name contained_within attribute:street_address callback/],
1171                 required => [qw/lat long name/],
1172                 returns => 'HashRef',
1173                 description => <<'EOT',
1174             Locates places near the given coordinates which are similar in name.
1175            
1176             Conceptually you would use this method to get a list of known places to choose
1177             from first. Then, if the desired place doesn't exist, make a request to
1178             C<add_place> to create a new one.
1179            
1180             The token contained in the response is the token needed to be able to create a
1181             new place.
1182             EOT
1183              
1184             );
1185              
1186             twitter_api_method add_place => (
1187                 path => 'geo/place',
1188                 method => 'POST',
1189                 params => [qw/name contained_within token lat long attribute:street_address callback/],
1190                 required => [qw/name contained_within token lat long/],
1191                 returns => 'Place',
1192                 description => <<'EOT',
1193             Creates a new place object at the given latitude and longitude.
1194            
1195             Before creating a place you need to query C<similar_places> with the latitude,
1196             longitude and name of the place you wish to create. The query will return an
1197             array of places which are similar to the one you wish to create, and a token.
1198             If the place you wish to create isn't in the returned array you can use the
1199             token with this method to create a new one.
1200             EOT
1201              
1202             );
1203              
1204             twitter_api_method lookup_users => (
1205                 path => 'users/lookup',
1206                 method => 'GET',
1207                 params => [qw/user_id screen_name include_entities/],
1208                 booleans => [qw/include_entities/],
1209                 required => [],
1210                 returns => 'ArrayRef[User]',
1211                 description => <<'EOT'
1212             Return up to 100 users worth of extended information, specified by either ID,
1213             screen name, or combination of the two. The author's most recent status (if the
1214             authenticating user has permission) will be returned inline. This method is
1215             rate limited to 1000 calls per hour.
1216            
1217             This method will accept user IDs or screen names as either a comma delimited
1218             string, or as an ARRAY ref. It will also accept arguments in the normal
1219             HASHREF form or as a simple list of named arguments. I.e., any of the
1220             following forms are acceptable:
1221            
1222             $nt->lookup_users({ user_id => '1234,6543,3333' });
1223             $nt->lookup_users(user_id => '1234,6543,3333');
1224             $nt->lookup_users({ user_id => [ 1234, 6543, 3333 ] });
1225             $nt->lookup_users({ screen_name => 'fred,barney,wilma' });
1226             $nt->lookup_users(screen_name => ['fred', 'barney', 'wilma']);
1227            
1228             $nt->lookup_users(
1229             screen_name => ['fred', 'barney' ],
1230             user_id => '4321,6789',
1231             );
1232            
1233             EOT
1234             );
1235              
1236             twitter_api_method retweeted_by => (
1237                 path => 'statuses/:id/retweeted_by',
1238                 method => 'GET',
1239                 params => [qw/id count page trim_user include_entities/],
1240                 booleans => [qw/include_entities trim_user/],
1241                 required => [qw/id/],
1242                 returns => 'ArrayRef[User]',
1243                 description => <<''
1244             Returns up to 100 users who retweeted the status identified by C<id>.
1245            
1246             );
1247              
1248             twitter_api_method retweeted_by_ids => (
1249                 path => 'statuses/:id/retweeted_by/ids',
1250                 method => 'GET',
1251                 params => [qw/id count page trim_user include_entities/],
1252                 booleans => [qw/include_entities trim_user/],
1253                 required => [qw/id/],
1254                 returns => 'ArrayRef[User]',
1255                 description => <<''
1256             Returns the IDs of up to 100 users who retweeted the status identified by C<id>.
1257            
1258             );
1259              
1260             twitter_api_method friendships_incoming => (
1261                 path => 'friendships/incoming',
1262                 method => 'GET',
1263                 params => [qw/cursor/],
1264                 required => [qw/cursor/],
1265                 returns => 'HashRef',
1266                 description => <<'',
1267             Returns an HASH ref with an array of numeric IDs in the C<ids> element for
1268             every user who has a pending request to follow the authenticating user.
1269            
1270             );
1271              
1272             twitter_api_method friendships_outgoing => (
1273                 path => 'friendships/outgoing',
1274                 method => 'GET',
1275                 params => [qw/cursor/],
1276                 required => [qw/cursor/],
1277                 returns => 'HashRef',
1278                 description => <<'',
1279             Returns an HASH ref with an array of numeric IDs in the C<ids> element for
1280             every protected user for whom the authenticating user has a pending follow
1281             request.
1282            
1283             );
1284              
1285             # new in 3.17001 2010-10-19
1286              
1287             twitter_api_method account_totals => (
1288                 path => 'account/totals',
1289                 method => 'GET',
1290                 params => [],
1291                 required => [],
1292                 returns => 'HashRef',
1293                 description => <<''
1294             Returns the current count of friends, followers, updates (statuses)
1295             and favorites of the authenticating user.
1296            
1297             );
1298              
1299             twitter_api_method account_settings => (
1300                 path => 'account/settings',
1301                 method => 'GET',
1302                 params => [],
1303                 required => [],
1304                 returns => 'HashRef',
1305                 description => <<''
1306             Returns the current trend, geo and sleep time information for the
1307             authenticating user.
1308            
1309             );
1310              
1311             twitter_api_method suggestion_categories => (
1312                 path => 'users/suggestions',
1313                 method => 'GET',
1314                 params => [],
1315                 required => [],
1316                 returns => 'ArrayRef',
1317                 description => <<''
1318             Returns the list of suggested user categories. The category slug can be used in
1319             the C<user_suggestions> API method get the users in that category . Does not
1320             require authentication.
1321            
1322             );
1323              
1324             twitter_api_method user_suggestions => (
1325                 aliases => [qw/follow_suggestions/],
1326                 path => 'users/suggestions/:category/members',
1327                 method => 'GET',
1328                 params => [qw/category lang/],
1329                 required => [qw/category/],
1330                 returns => 'ArrayRef',
1331                 description => <<''
1332             Access the users in a given category of the Twitter suggested user list and
1333             return their most recent status if they are not a protected user. Currently
1334             supported values for optional parameter C<lang> are C<en>, C<fr>, C<de>, C<es>,
1335             C<it>. Does not require authentication.
1336            
1337             );
1338              
1339             twitter_api_method show_direct_message => (
1340                 path => 'direct_messages/show/:id',
1341                 method => 'GET',
1342                 params => [qw/id include_entities/],
1343                 booleans => [qw/include_entities/],
1344                 required => [qw/id/],
1345                 returns => 'HashRef',
1346                 description => <<''
1347             Returns a single direct message, specified by an id parameter. Like
1348             the C<direct_messages> request, this method will include the
1349             user objects of the sender and recipient. Requires authentication.
1350            
1351             );
1352              
1353             twitter_api_method retweeted_to_user => (
1354                 path => 'statuses/retweeted_to_user',
1355                 method => 'GET',
1356                 params => [qw/id user_id screen_name/],
1357                 required => [qw/id/],
1358                 returns => 'ArrayRef',
1359                 description => <<''
1360             Returns the 20 most recent retweets posted by users the specified user
1361             follows. The user is specified using the user_id or screen_name
1362             parameters. This method is identical to C<retweeted_to_me>
1363             except you can choose the user to view.
1364             Does not require authentication, unless the user is protected.
1365            
1366             );
1367              
1368             twitter_api_method retweeted_by_user => (
1369                 path => 'statuses/retweeted_by_user',
1370                 method => 'GET',
1371                 params => [qw/id user_id screen_name/],
1372                 required => [qw/id/],
1373                 returns => 'ArrayRef',
1374                 description => <<''
1375             Returns the 20 most recent retweets posted by the specified user. The user is
1376             specified using the user_id or screen_name parameters. This method is identical
1377             to C<retweeted_by_me> except you can choose the user to view. Does not require
1378             authentication, unless the user is protected.
1379            
1380             );
1381              
1382             twitter_api_method lookup_friendships => (
1383                 path => 'friendships/lookup',
1384                 method => 'GET',
1385                 params => [qw/user_id screen_name/],
1386                 required => [],
1387                 returns => 'ArrayRef',
1388                 description => <<''
1389             Returns the relationship of the authenticating user to the comma separated list
1390             or ARRAY ref of up to 100 screen_names or user_ids provided. Values for
1391             connections can be: following, following_requested, followed_by, none.
1392             Requires authentication.
1393            
1394             );
1395              
1396             twitter_api_method update_friendship => (
1397                 path => 'friendships/update',
1398                 method => 'POST',
1399                 params => [qw/id user_id screen_name device retweets/],
1400                 required => [qw/id/],
1401                 booleans => [qw/device retweets/],
1402                 returns => 'HashRef',
1403                 description => <<''
1404             Allows you enable or disable retweets and device notifications from the
1405             specified user. All other values are assumed to be false. Requires
1406             authentication.
1407            
1408             );
1409              
1410             twitter_api_method related_results => (
1411                 path => 'related_results/show/:id',
1412                 method => 'GET',
1413                 params => [qw/id/],
1414                 required => [qw/id/],
1415                 returns => 'ArrayRef[Status]',
1416                 description => <<''
1417             If available, returns an array of replies and mentions related to the specified
1418             status. There is no guarantee there will be any replies or mentions in the
1419             response. This method is only available to users who have access to
1420             #newtwitter. Requires authentication.
1421            
1422             );
1423              
1424             ### Lists ###
1425              
1426             twitter_api_method all_subscriptions => (
1427                 path => 'lists/all',
1428                 method => 'GET',
1429                 params => [qw/user_id screen_name count cursor/],
1430                 required => [],
1431                 returns => 'ArrayRef[List]',
1432                 aliases => [qw/all_lists list_subscriptions/],
1433                 description => <<'',
1434             Returns all lists the authenticating or specified user subscribes to, including
1435             their own. The user is specified using the user_id or screen_name parameters.
1436             If no user is given, the authenticating user is used.
1437            
1438             );
1439              
1440             twitter_api_method list_statuses => (
1441                 path => 'lists/statuses',
1442                 method => 'GET',
1443                 params => [qw/
1444             list_id slug owner_screen_name owner_id since_id max_id per_page page
1445             include_entities include_rts
1446             /],
1447                 required => [],
1448                 booleans => [qw/include_entities include_rts/],
1449                 returns => 'ArrayRef[Status]',
1450                 description => <<'',
1451             Returns tweet timeline for members of the specified list. Historically,
1452             retweets were not available in list timeline responses but you can now use the
1453             include_rts=true parameter to additionally receive retweet objects.
1454            
1455             );
1456              
1457             twitter_api_method delete_list_member => (
1458                 path => 'lists/members/destroy',
1459                 method => 'POST',
1460                 params => [qw/list_id slug user_id screen_name owner_screen_name owner_id/],
1461                 required => [],
1462                 returns => 'User',
1463                 aliases => [qw/remove_list_member/],
1464                 description => <<'',
1465             Removes the specified member from the list. The authenticated user must be the
1466             list's owner to remove members from the list.
1467            
1468             );
1469              
1470             twitter_api_method list_memberships => (
1471                 path => 'lists/memberships',
1472                 method => 'GET',
1473                 params => [qw/user_id screen_name cursor filter_to_owned_lists/],
1474                 required => [],
1475                 booleans => [qw/filter_to_owned_lists/],
1476                 returns => 'Hashref',
1477                 description => <<'',
1478             Returns the lists the specified user has been added to. If user_id or
1479             screen_name are not provided the memberships for the authenticating user are
1480             returned.
1481            
1482             );
1483              
1484             twitter_api_method list_subscribers => (
1485                 path => 'lists/subscribers',
1486                 method => 'GET',
1487                 params => [qw/list_id slug owner_screen_name owner_id cursor include_entities skip_status/],
1488                 required => [],
1489                 booleans => [qw/include_entities skip_status/],
1490                 returns => 'Hashref',
1491                 description => <<'',
1492             Returns the subscribers of the specified list. Private list subscribers will
1493             only be shown if the authenticated user owns the specified list.
1494            
1495             );
1496              
1497             twitter_api_method subscribe_list => (
1498                 path => 'lists/subscribers/create',
1499                 method => 'POST',
1500                 params => [qw/owner_screen_name owner_id list_id slug/],
1501                 required => [],
1502                 returns => 'List',
1503                 description => <<'',
1504             Subscribes the authenticated user to the specified list.
1505            
1506             );
1507              
1508             twitter_api_method is_list_subscriber => (
1509                 path => 'lists/subscribers/show',
1510                 method => 'GET',
1511                 params => [qw/
1512             owner_screen_name owner_id list_id slug user_id screen_name
1513             include_entities skip_status
1514             /],
1515                 required => [],
1516                 booleans => [qw/include_entities skip_status/],
1517                 returns => 'Maybe[User]',
1518                 aliases => [qw/is_subscribed_list/],
1519                 description => <<'',
1520             Check if the specified user is a subscriber of the specified list. Returns the
1521             user or undef.
1522            
1523             );
1524              
1525             around [qw/is_list_subscriber is_subscribed_list/] => sub {
1526                 my $orig = shift;
1527                 my $self = shift;
1528              
1529                 $self->_user_or_undef($orig, 'subscriber', @_);
1530             };
1531              
1532             twitter_api_method unsubscribe_list => (
1533                 path => 'lists/subscribers/destroy',
1534                 method => 'POST',
1535                 params => [qw/list_id slug owner_screen_name owner_id/],
1536                 required => [],
1537                 returns => 'List',
1538                 description => <<'',
1539             Unsubscribes the authenticated user from the specified list.
1540            
1541             );
1542              
1543             twitter_api_method members_create_all => (
1544                 path => 'lists/members/create_all',
1545                 method => 'POST',
1546                 params => [qw/list_id slug owner_screen_name owner_id/],
1547                 required => [],
1548                 returns => 'List',
1549                 aliases => [qw/add_list_members/],
1550                 description => <<'',
1551             Adds multiple members to a list, by specifying a reference to an array or a
1552             comma-separated list of member ids or screen names. The authenticated user must
1553             own the list to be able to add members to it. Note that lists can't have more
1554             than 500 members, and you are limited to adding up to 100 members to a list at
1555             a time with this method.
1556            
1557             );
1558              
1559             twitter_api_method members_destroy_all => (
1560                 path => 'lists/members/destroy_all',
1561                 method => 'POST',
1562                 params => [qw/list_id slug user_id screen_name owner_screen_name owner_id/],
1563                 required => [],
1564                 returns => 'List',
1565                 aliases => [qw/remove_list_members/],
1566                 description => <<'EOT',
1567             Removes multiple members from a list, by specifying a reference to an array of
1568             member ids or screen names, or a string of comma separated user ids or screen
1569             names. The authenticated user must own the list to be able to remove members
1570             from it. Note that lists can't have more than 500 members, and you are limited
1571             to removing up to 100 members to a list at a time with this method.
1572            
1573             Please note that there can be issues with lists that rapidly remove and add
1574             memberships. Take care when using these methods such that you are not too
1575             rapidly switching between removals and adds on the same list.
1576            
1577             EOT
1578             );
1579              
1580             twitter_api_method is_list_member => (
1581                 path => 'lists/members/show',
1582                 method => 'GET',
1583                 params => [qw/
1584             owner_screen_name owner_id list_id slug user_id screen_name
1585             include_entities skip_status
1586             /],
1587                 required => [],
1588                 booleans => [qw/include_entities skip_status/],
1589                 returns => 'Maybe[User]',
1590                 description => <<'',
1591             Check if the specified user is a member of the specified list. Returns the user or undef.
1592            
1593             );
1594              
1595             around is_list_member => sub {
1596                 my $orig = shift;
1597                 my $self = shift;
1598              
1599                 $self->_user_or_undef($orig, 'member', @_);
1600             };
1601              
1602             twitter_api_method list_members => (
1603                 path => 'lists/members',
1604                 method => 'GET',
1605                 params => [qw/
1606             list_id slug owner_screen_name owner_id cursor
1607             include_entities skip_status
1608             /],
1609                 required => [],
1610                 booleans => [qw/include_entities skip_status/],
1611                 returns => 'Hashref',
1612                 description => <<'',
1613             Returns the members of the specified list. Private list members will only be
1614             shown if the authenticated user owns the specified list.
1615            
1616             );
1617              
1618             twitter_api_method add_list_member => (
1619                 path => 'lists/members/create',
1620                 method => 'POST',
1621                 params => [qw/list_id slug user_id screen_name owner_screen_name owner_id/],
1622                 required => [],
1623                 returns => 'User',
1624                 description => <<'',
1625             Add a member to a list. The authenticated user must own the list to be able to
1626             add members to it. Note that lists can't have more than 500 members.
1627            
1628             );
1629              
1630             twitter_api_method delete_list => (
1631                 path => 'lists/destroy',
1632                 method => 'POST',
1633                 params => [qw/owner_screen_name owner_id list_id slug/],
1634                 required => [],
1635                 returns => 'List',
1636                 description => <<'',
1637             Deletes the specified list. The authenticated user must own the list to be able
1638             to destroy it.
1639            
1640             );
1641              
1642             twitter_api_method update_list => (
1643                 path => 'lists/update',
1644                 method => 'POST',
1645                 params => [qw/list_id slug name mode description owner_screen_name owner_id/],
1646                 required => [],
1647                 returns => 'List',
1648                 description => <<'',
1649             Updates the specified list. The authenticated user must own the list to be able
1650             to update it.
1651            
1652             );
1653              
1654             twitter_api_method create_list => (
1655                 path => 'lists/create',
1656                 method => 'POST',
1657                 params => [qw/list_id slug name mode description owner_screen_name owner_id/],
1658                 required => [],
1659                 returns => 'List',
1660                 description => <<'',
1661             Creates a new list for the authenticated user. Note that you can't create more
1662             than 20 lists per account.
1663            
1664             );
1665              
1666             twitter_api_method get_lists => (
1667                 path => 'lists',
1668                 method => 'GET',
1669                 params => [qw/user_id screen_name cursor/],
1670                 required => [],
1671                 returns => 'Hashref',
1672                 aliases => [qw/list_lists/],
1673                 description => <<'',
1674             Returns the lists of the specified (or authenticated) user. Private lists will
1675             be included if the authenticated user is the same as the user whose lists are
1676             being returned.
1677            
1678             );
1679              
1680             twitter_api_method get_list => (
1681                 path => 'lists/show',
1682                 method => 'GET',
1683                 params => [qw/list_id slug owner_screen_name owner_id/],
1684                 required => [],
1685                 returns => 'List',
1686                 description => <<'',
1687             Returns the specified list. Private lists will only be shown if the
1688             authenticated user owns the specified list.
1689            
1690             );
1691              
1692             twitter_api_method subscriptions => (
1693                 path => 'lists/subscriptions',
1694                 method => 'GET',
1695                 params => [qw/user_id screen_name count cursor/],
1696                 required => [],
1697                 returns => 'ArrayRef[List]',
1698                 aliases => [],
1699                 description => <<'',
1700             Obtain a collection of the lists the specified user is subscribed to, 20 lists
1701             per page by default. Does not include the user's own lists.
1702            
1703             );
1704              
1705             ### Legal ###
1706              
1707             twitter_api_method get_privacy_policy => (
1708                 path => 'legal/privacy',
1709                 method => 'GET',
1710                 params => [],
1711                 required => [],
1712                 returns => 'HashRef',
1713                 description => <<'',
1714             Returns Twitter's privacy policy.
1715            
1716             );
1717              
1718             twitter_api_method get_tos => (
1719                 path => 'legal/tos',
1720                 method => 'GET',
1721                 params => [],
1722                 required => [],
1723                 returns => 'HashRef',
1724                 description => <<'',
1725             Returns the Twitter Terms of Service. These are not the same as the Developer
1726             Rules of the Road.
1727            
1728             );
1729              
1730             1;
1731              
1732             __END__
1733            
1734             =head1 NAME
1735            
1736             Net::Twitter::Role::API::REST - A definition of the Twitter REST API as a Moose role
1737            
1738             =head1 VERSION
1739            
1740             version 4.01042
1741            
1742             =head1 SYNOPSIS
1743            
1744             package My::Twitter;
1745             use Moose;
1746             with 'Net::Twitter::API::REST';
1747            
1748             =head1 DESCRIPTION
1749            
1750             B<Net::Twitter::Role::API::REST> provides definitions for all the Twitter REST API
1751             methods. Applying this role to any class provides methods for all of the
1752             Twitter REST API methods.
1753            
1754            
1755             =head1 AUTHOR
1756            
1757             Marc Mims <marc@questright.com>
1758            
1759             =head1 LICENSE
1760            
1761             Copyright (c) 2016 Marc Mims
1762            
1763             The Twitter API itself, and the description text used in this module is:
1764            
1765             Copyright (c) 2009 Twitter
1766            
1767             This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1768            
1769             =head1 DISCLAIMER OF WARRANTY
1770            
1771             BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
1772             FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
1773             OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
1774             PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
1775             EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1776             WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
1777             ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
1778             YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
1779             NECESSARY SERVICING, REPAIR, OR CORRECTION.
1780            
1781             IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
1782             WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
1783             REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE
1784             LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
1785             OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
1786             THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
1787             RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
1788             FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
1789             SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
1790             SUCH DAMAGES.
1791