Skip to content
Browse files

WIP: folding v1.1 in

  • Loading branch information...
1 parent ceca106 commit ac038de0ab29aa5319708caa0153741d2e56d2d3 @semifor semifor committed Jan 25, 2013
View
2 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 ) {
View
2 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,
View
2 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,
View
2 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/ ];
View
2 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.
View
4 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/]);
View
9 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.
View
4 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,
View
10 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);
View
5 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',
View
2 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,
);
View
2 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'],
);
View
61 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

0 comments on commit ac038de

Please sign in to comment.
Something went wrong with that request. Please try again.