Your Twitter Apps may break
On 25-Mar-2011, Twitter announced changes to the API. If your code
currently uses the friends_ids or followers_ids methods, without the
cursor parameter, it will soon break!
Twitter intends to start forcing the use of cursored calls. If you do not
provide a cursor parameter, Twitter will add one for you, with value -1.
This will change the return value! Instead of getting an array reference, you
will get a hash reference, with the array of returned IDs nested within it.
Let’s pick on @miyagawa. He as a lot of followers.
my $r = $nt->followers_ids('miyagawa');
The call above currently returns 9,191 IDs:
[ 151398039, 272906704, 197990177, 9431032, 271536579... ]
When Twitter begins forcing cursored calls, that same call will return:
{
ids => [
151398039, 272906704, 197990177, 9431032, 271536579...
],
next_cursor => 1317952939226585828,
next_cursor_str => 1317952939226585828,
previous_cursor => 0,
previous_cursor_str => 0,
}
where $r->{ids} contains @miyagawa’s most recent 5,000 followers.
The Net::Twitter documentation includes information on how to use the cursor
parameter.
To help with the transition, I created a new trait for Net::Twitter which
will transparently handled cursored calls.
AutoCursor
When applied, the AutoCursor trait will first attempt a friends_ids or
followers_ids call without a cursor parameter (unless you supply one). If
Twitter forces a cursored call by adding the cursor parameter, AutoCursor
will automatically call the underlying API method in a loop for up to 16 calls
and return a reference to an array with the combined results.
This limits the change required to your code to just the Net::Twitter->new
call and handles users with up to 80,000 friends or followers transparently.
The AutoCursor trait is parameterized, so you can customize its behavior:
$nt = Net::Twitter->new(
traits => [
qw/API::REST RetryOnError OAuth/,
AutoCursor => { max_calls => 40 },
],
# additional new arguments...
);
With this max_calls parameter, followers_ids will make up to 40 underlying
API calls returning up to 200,000 IDs.
When using AutoCursor if you supply a cursor parameter to the call, it
will use that parameter for the first call, rather than doing an initial
cursor-less call.
You can also use AutoCursor for other calls that accept a cursor parameter.
For example:
$nt = Net::Twitter->new(
traits => [
qw/API::REST RetryOnError OAuth/,
AutoCursor => { max_calls => 40 },
AutoCursor => {
max_calls => 5,
force_cursor => 1,
array_accessor => 'users',
methods => [qw/friends followers/],
},
],
# additional new arguments...
);
With the Net::Twitter object above, calls to friends will return a
reference to an array with up to 500 users.
The AutoCursor role is currently in a developer release.
http://search.cpan.org/~mmims/Net-Twitter-3.16000_1/
UPDATED 2011-03-29: AutoCursor is now available in the production release
with a minor change that allows the override of max_calls on a per-call basis:
$nt = Net::Twitter->new(traits => [qw/API::REST AutoCursor ...
$ids = $nt->followers_ids; # up to 16 calls; 80,000 ids
$ids = $nt->followers_ids({ max_calls => 40 }); # up to 200,000 ids
I would appreciate some feedback from those who will be affected by this
Twitter API change before adding AutoCursor to the production release. Does
it meet your needs? Is the interface sufficient? Please test it with your
code and let me know what you think. You can comment here, shout at me on
Twitter (either @semifor or @perl_api), or drop by the
#net-twitter channel at irc.perl.org.
