WIP: folding v1.1 in

examples/oauth_desktop.pl

@@ -21,7 +21,7 @@
 my (undef, undef, $datafile) = File::Spec->splitpath($0);
 $datafile =~ s/\..*/.dat/;
 
-my $nt = Net::Twitter->new(traits => [qw/API::REST OAuth/], %consumer_tokens);
+my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1/], %consumer_tokens);
 my $access_tokens = eval { retrieve($datafile) } || [];
 
 if ( @$access_tokens ) {

examples/oauth_webapp.pl

@@ -19,7 +19,7 @@ package MyWebApp;
 
 my $server_port = 8080;
 
-sub twitter { shift->{twitter} ||= Net::Twitter->new(traits => [qw/API::REST OAuth/], %consumer_tokens) }
+sub twitter { shift->{twitter} ||= Net::Twitter->new(traits => [qw/API::RESTv1_1/], %consumer_tokens) }
 
 my %dispatch = (
     '/oauth_callback' => \&oauth_callback,

lib/Net/Identica.pm

@@ -50,7 +50,7 @@ features and functionality (OAuth, Search, exceptions on error, etc.).
 
   # A more complex object with OAuth and some optional traits
   my $identica = Net::Twitter->new(
-      traits => [qw/API::REST API::Search OAuth InflateObjects/],
+      traits => [qw/API::REST API::Search InflateObjects/],
       identica            => 1,
       consumer_key        => $consumer_key,
       consumer_secret     => $consumer_secret,

lib/Net/Twitter.pm

@@ -117,7 +117,7 @@ sub new {
         croak "Options 'legacy' and 'traits' are mutually exclusive. Use only one."
             if $traits;
 
-        $traits = [ $legacy ? 'Legacy' : 'API::REST' ];
+        $traits = [ $legacy ? 'Legacy' : 'API::RESTv1_1' ];
     }
 
     $traits ||= [ qw/Legacy/ ];

lib/Net/Twitter/API.pm

@@ -186,7 +186,7 @@ Net::Twitter::API - Moose sugar for defining Twitter API methods
 =head1 DESCRIPTION
 
 This module provides some Moose sugar for defining Twitter API methods.  It is part
-of the Net-Twitter distribution on CPAN and is used by C<Net::Twitter::API::REST>,
+of the Net-Twitter distribution on CPAN and is used by C<Net::Twitter::API::RESTv1_1>,
 C<Net::Twitter::API::Search>, and perhaps others.
 
 It's intent is to make maintaining C<Net::Twitter> as easy as possible.

lib/Net/Twitter/OAuth.pm

@@ -42,10 +42,10 @@ This module is deprecated.  Use L<Net::Twitter> instead.
     use Net::Twitter;
 
     # Just the REST API; exceptions thrown on error
-    $nt = Net::Twitter->new(traits => [qw/API::REST OAuth/]);
+    $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/]);
 
     # Just the REST API; errors wrapped - use $nt->get_error
-    $nt = Net::Twitter->new(traits => [qw/API::REST WrapError/]);
+    $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 WrapError/]);
 
     # Or, for code that uses legacy Net::Twitter idioms
     $nt = Net::Twitter->new(traits => [qw/Legacy OAuth/]);

lib/Net/Twitter/Role/API/RESTv1_1.pm

@@ -7,7 +7,6 @@ use URI;
 
 # API v1.1 incorporoates the Search and Upload APIs
 excludes map "Net::Twitter::Role::$_", qw/API::Search API::Upload Net::Twitter::Role::RateLimit/;
-with qw/Net::Twitter::Role::OAuth/;
 
 has apiurl          => ( isa => 'Str', is => 'ro', default => 'http://api.twitter.com/1.1'  );
 has apihost         => ( isa => 'Str', is => 'ro', lazy => 1, builder => '_build_apihost' );
@@ -1889,18 +1888,18 @@ __END__
 
 =head1 NAME
 
-Net::Twitter::Role::API::REST - A definition of the Twitter REST API as a Moose role
+Net::Twitter::Role::API::RESTv1_1 - A definition of the Twitter REST API v1.1 as a Moose role
 
 =head1 SYNOPSIS
 
   package My::Twitter;
   use Moose;
-  with 'Net::Twitter::API::REST';
+  with 'Net::Twitter::API::RESTv1_1';
 
 =head1 DESCRIPTION
 
-B<Net::Twitter::Role::API::REST> provides definitions for all the Twitter REST API
-methods.  Applying this role to any class provides methods for all of the
+B<Net::Twitter::Role::API::RESTv1_1> provides definitions for all the Twitter REST API
+v1.1 methods.  Applying this role to any class provides methods for all of the
 Twitter REST API methods.
 
 

lib/Net/Twitter/Role/AutoCursor.pm

@@ -69,7 +69,7 @@ Net::Twitter::Role::AutoCursor - Help transition to cursor based access to frien
 
   use Net::Twitter;
   my $nt = Net::Twitter->new(
-      traits => [qw/AutoCursor API::REST RetryOnError OAuth/],
+      traits => [qw/AutoCursor API::RESTv1_1 RetryOnError OAuth/],
       # additional ags...
   );
 
@@ -78,7 +78,7 @@ Net::Twitter::Role::AutoCursor - Help transition to cursor based access to frien
 
   my $nt = Net::Twitter->new(
       traits => [
-          qw/API::REST RetryOnError OAuth/
+          qw/API::RESTv1_1 RetryOnError OAuth/
           AutoCursor => { max_calls => 32 },
           AutoCursor => {
               max_calls      => 4,

lib/Net/Twitter/Role/OAuth.pm

@@ -265,7 +265,7 @@ Net::Twitter::Role::OAuth - Net::Twitter role that provides OAuth instead of Bas
   use Net::Twitter;
 
   my $nt = Net::Twitter->new(
-      traits          => ['API::REST', 'OAuth'],
+      traits          => ['API::RESTv1_1', 'OAuth'],
       consumer_key    => "YOUR-CONSUMER-KEY",
       consumer_secret => "YOUR-CONSUMER-SECRET",
   );
@@ -299,7 +299,7 @@ Here's how to authorize users as a desktop app mode:
   use Net::Twitter;
 
   my $nt = Net::Twitter->new(
-      traits          => ['API::REST', 'OAuth'],
+      traits          => ['API::RESTv1_1', 'OAuth'],
       consumer_key    => "YOUR-CONSUMER-KEY",
       consumer_secret => "YOUR-CONSUMER-SECRET",
   );
@@ -331,7 +331,7 @@ authorization URL.
   sub twitter_authorize : Local {
       my($self, $c) = @_;
 
-      my $nt = Net::Twitter->new(traits => [qw/API::REST OAuth/], %param);
+      my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
       my $url = $nt->get_authorization_url(callback => $callbackurl);
 
       $c->response->cookies->{oauth} = {
@@ -353,7 +353,7 @@ secret to upgrade the request token to access token.
       my %cookie = $c->request->cookies->{oauth}->value;
       my $verifier = $c->req->params->{oauth_verifier};
 
-      my $nt = Net::Twitter->new(traits => [qw/API::REST OAuth/], %param);
+      my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
       $nt->request_token($cookie{token});
       $nt->request_token_secret($cookie{token_secret});
 
@@ -371,7 +371,7 @@ before calling any Twitter API methods.
 
       my($access_token, $access_token_secret) = ...;
 
-      my $nt = Net::Twitter->new(traits => [qw/API::REST OAuth/], %param);
+      my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
       $nt->access_token($access_token);
       $nt->access_token_secret($access_token_secret);
 

lib/Net/Twitter/Role/RateLimit.pm

@@ -12,7 +12,7 @@ Net::Twitter::Role::RateLimit - Rate limit features for Net::Twitter
 
     use Net::Twitter;
     my $nt = Net::Twitter->new(
-        traits => [qw/API::REST RateLimit/],
+        traits => [qw/API::RESTv1_1 RateLimit/],
         %other_options,
     );
 
@@ -29,6 +29,9 @@ rate limit status.
 
 requires qw/ua rate_limit_status/;
 
+# Rate limiting changed so dramatically with v1.1 this Role simply won't work with it
+excludes 'Net::Twitter::Role::API::RESTv1_1';
+
 has _rate_limit_status => (
     isa      => 'HashRef[Int]',
     is       => 'rw',

lib/Net/Twitter/Role/RetryOnError.pm

@@ -13,7 +13,7 @@ Net::Twitter::Role::RetryOnError - Retry Twitter API calls on error
 
     use Net::Twitter;
     $nt = Net::Twitter->new(
-        traits      => ['API::REST', 'RetryOnError']
+        traits      => ['API::RESTv1_1', 'RetryOnError']
         max_retries => 3,
     );
 

lib/Net/Twitter/Role/SimulateCursors.pm

@@ -43,7 +43,7 @@ Net::Twitter::Role::SimulateCursors - Make paging work like cursoring
   use Net::Twitter;
 
   my $nt = Net::Twitter->new(
-      traits          => ['API::REST', 'SimulateCursors'],
+      traits          => ['API::RESTv1_1', 'SimulateCursors'],
   );
 
 

src/net-twitter-pod.tt2

@@ -16,7 +16,7 @@ This document describes Net::Twitter version [% VERSION %]
 
   # As of 13-Aug-2010, Twitter requires OAuth for authenticated requests
   my $nt = Net::Twitter->new(
-      traits   => [qw/OAuth API::REST/],
+      traits   => [qw/API::RESTv1_1/],
       consumer_key        => $consumer_key,
       consumer_secret     => $consumer_secret,
       access_token        => $token,
@@ -45,6 +45,23 @@ This document describes Net::Twitter version [% VERSION %]
 This module provides a perl interface to the Twitter APIs.  See
 L<http://dev.twitter.com/doc> for a full description of the Twitter APIs.
 
+=head1 TWITTER API VERSION 1.1
+
+Twitter will (perhaps has by the time you read this) deprecated version 1 of
+the API. Documentation, here, assumes version 1.1 of the API. For version 1
+documentation, see L<Net::Twitter::Role::API::REST>.
+
+To use Twitter API version 1.1, simply replace C<API::REST> in the C<traits>
+argument to C<new> with C<API::RESTv1_1>. The C<Net::Twitter> API is backwards
+compatible to the extent possible. If Twitter does not provide a 1.1 endpoint
+for a version 1 call, C<Net::Twitter> cannot support it, of course.
+
+Twitter API version 1.1 requires OAuth authentication for all calls. There is
+no longer an IP address limit and a per-user limit. Each API call has it's own
+rate limit. Most are 15 calls reset every 15 minutes. Others are 180 calls,
+reset every 15 minutes. These limits may change. For current rate limits,
+see L<https://dev.twitter.com/docs/rate-limiting/1.1/limits>.
+
 =head1 OMG! THE MOOSE!
 
 Net::Twitter is L<Moose> based. Moose provides some advantages, including the
@@ -102,9 +119,9 @@ values are:
 
 =over 4
 
-=item API::REST
+=item API::RESTv1_1
 
-Provides support for the Twitter REST API methods.
+Provides support for the Twitter REST API version 1.1 methods.
 
 =item API::Search
 
@@ -183,16 +200,13 @@ handled in Net::Twitter versions prior to version 3.00.
 Some examples of using the C<traits> parameter in C<new>:
 
     # provide support for *only* the REST API; throw exceptions on error
-    $nt = Net::Twitter->new(traits => ['API::REST']);
+    $nt = Net::Twitter->new(traits => ['API::RESTv1_1']);
 
     # provide support for both the REST and Search APIs; wrap errors
-    $nt = Net::Twitter->new(traits => [qw/API::REST API::Search WrapError/]);
-
-    # ensure full legacy support
-    $nt = Net::Twitter->new(traits => ['Legacy']);
+    $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 API::Search WrapError/]);
 
-    # currently, these 2 calls to new are equivalent:
-    $nt = Net::Twitter->new();
+    # Provide legacy support for applications written with Net::Twitter
+    # prior to version 3.0.
     $nt = Net::Twitter->new(traits => ['Legacy']);
 
 =item legacy
@@ -204,7 +218,7 @@ implementing the REST API and throws exceptions on API method errors.
 
 is a shortcut for:
 
-    Net::Twitter->new(traits => ['API::REST']);
+    Net::Twitter->new(traits => ['API::RESTv1_1']);
 
 If set to 1, C<new> constructs a C<Net::Twitter> object with the C<Legacy> trait.
 
@@ -267,7 +281,7 @@ originally used by Twitter to provide an "via" application byline.
 =item apiurl
 
 The URL for the Twitter API. This defaults to "http://api.twitter.com/1". This
-option is available when the C<API::REST> trait is included.
+option is available when the C<API::RESTv1_1> trait is included.
 
 =item apihost
 
@@ -276,15 +290,15 @@ DEPRECATED - Setting the C<apiurl> is sufficient.
 =item apirealm
 
 A string containing the Twitter API realm used for Basic Authentication. It
-defaults to "Twitter API".  This option is available when the C<API::REST>
+defaults to "Twitter API".  This option is available when the C<API::RESTv1_1>
 trait is included.
 
 =item identica
 
 If set to 1, C<Net::Twitter> overrides the defaults for C<apiurl>, C<apihost>,
 and C<apirealm> to "http://identi.ca/api", "identi.ca:80", and "Laconica API"
 respectively.  It defaults to 0.  This option is available when the
-C<API::REST> trait is included.
+C<API::RESTv1_1> trait is included.
 
 =item consumer_key
 
@@ -344,13 +358,15 @@ C<Net::Twitter>.  Use it with caution.
 
 =head1 AUTHENTICATION
 
-As of 31-Aug-2010, Twitter requires OAuth for authenticated requests.  Other
+With REST API version 1.1, all API calls require OAuth. Since 
+31-Aug-2010, version 1 required OAuth requests requiring authentication.  Other
 Twitter compatible services, like Identi.ca, accept Basic Authentication.  So,
 C<Net::Twitter> provides support for both.
 
-To set up OAuth, include the C<OAuth> trait and include the C<consumer_key> and
-C<consumer_secret> options to L</new>.  See L<Net::Twitter::Role::OAuth> for
-more information on using OAuth, including examples.
+To set up OAuth, include the C<consumer_key> and C<consumer_secret> options to
+L</new>. When they are provided, the C<OAuth> trait will be automatically
+included.  See L<Net::Twitter::Role::OAuth> for more information on using
+OAuth, including examples.
 
 To set up Basic Authentication in C<Net::Twitter>, provide the C<username> and
 C<password> options to L</new> or call the L</credentials> method.
@@ -362,9 +378,8 @@ authentication header, pass C<< -authenticate => 0 >>.  Even if requested, an
 Authorization header will not be added if there are no user credentials
 (username and password for Basic Authentication; access tokens for OAuth).
 
-This is probably only useful for the L</rate_limit_status> method in the REST
-API, since it returns different values for an authenticated and a
-non-authenticated call.
+This is probably only useful for non-Twitter sites that use the Twitter API and
+support unauthenticated calls.
 
 =head1 API METHODS AND ARGUMENTS
 
@@ -506,7 +521,7 @@ option is ignored.
 
 =head1 REST API Methods
 
-These methods are provided when trait C<API::REST> is included in the C<traits>
+These methods are provided when trait C<API::RESTv1_1> is included in the C<traits>
 option to C<new>.
 
 =head2 Common Parameters
@@ -547,7 +562,7 @@ to indicate the numerical ID of the Twitter user that sent the status.
 
 =head2 Methods
 
-[% INCLUDE APIDOC class='API::REST' %]
+[% INCLUDE APIDOC class='API::RESTv1_1' %]
 [% INCLUDE APIDOC class='API::Upload' %]
 
 =head1 Search API Methods