Despite the removal of certain underlying functionality in Twitter API v1.1,
this library aims to preserve backward-compatibility wherever possible. For
example, despite the removal of the GET
statuses/retweeted_by_user resource, the
Twitter::API#retweeted_by_user method continues to exist, implemented by
making multiple requests to the GET statuses/user_timeline
resource. As a result, there is no longer a one-to-one correlation between
method calls and Twitter API requests. In fact, it's possible for a single
method call to exceed the Twitter API rate limit for a resource. If you think
this might cause a problem for your application, feel free to join the
discussion.

Rate Limiting

Another consequence of Twitter API v1.1 is that the
Twitter::Client#rate_limit method has been removed, since the concept of a
client-wide rate limit no longer exists. Rate limits are now applied on a
per-resource level, however, since there is no longer a one-to-one mapping
between methods and Twitter API resources, it's not entirely obvious how rate
limit information should be exposed. I've decided to go back to the pre-3.0.0
behavior of including rate limit information on Twitter::Error objects.
Here's an example of how to handle rate limits:

MAX_ATTEMPTS=3
num_attempts =0begin
num_attempts +=1
retweets =Twitter.retweeted_by_user("sferik")
rescueTwitter::Error::TooManyRequests => error
if num_attempts <=MAX_ATTEMPTS# NOTE: Your process could go to sleep for up to 15 minutes but if you# retry any sooner, it will almost certainly fail with the same exception.
sleep error.rate_limit.reset_in
retryelseraiseendend

Methods Missing

As a consequence of moving to Twitter API v1.1, the following methods from
version 3 are no longer available in version 4:

Twitter::API#accept

Twitter::API#deny

Twitter::API#disable_notifications

Twitter::API#enable_notifications

Twitter::API#end_session

Twitter::API#no_retweet_ids

Twitter::API#rate_limit_status

Twitter::API#rate_limited?

Twitter::API#recommendations

Twitter::API#related_results

Twitter::API#retweeted_to_user

Twitter::API#trends_daily

Twitter::API#trends_weekly

Twitter::Client#rate_limit

Twitter::RateLimit#class

Custom Endpoints

The Twitter::API#update_with_media method no longer uses the custom
upload.twitter.com endpoint, so media_endpoint configuration has been
removed. Likewise, the Twitter::API#search method no longer uses the custom
search.twitter.com endpoint, so search_endpoint configuration has also been
removed.

Errors

It's worth mentioning new error classes:

Twitter::Error::GatewayTimeout

Twitter::Error::TooManyRequests

Twitter::Error::UnprocessableEntity

In previous versions of this library, rate limit errors were indicated by
raising either Twitter::Error::BadRequest or
Twitter::Error::EnhanceYourCalm (for the Search API). As of version 4, the
library will raise Twitter::Error::TooManyRequests for all rate limit errors.
The Twitter::Error::EnhanceYourCalm class has been aliased to
Twitter::Error::TooManyRequests.

Configuration

Twitter API v1.1 requires you to authenticate via OAuth, so you'll need a
registered Twitter application. To register a new application, sign-in using
your Twitter account and the fill out the form at
http://dev.twitter.com/apps/new. If you've previously registered a Twitter
application, it will be listed at http://dev.twitter.com/apps. Once you've
registered an application, make sure to set the correct access level, otherwise
you may see the error:

Read-only application cannot POST

Your new application will be assigned a consumer key/secret pair and you will
be assigned an OAuth access token/secret pair for that application. You'll need
to configure these values before you make a request or else you'll get the
error:

Bad Authentication data

Applications that make requests on behalf of a single Twitter user can pass
global configuration options as a block to the Twitter.configure method.

Thread Safety

Applications that make requests on behalf of multiple Twitter users should
avoid using global configuration. In this case, you may still specify the
consumer_key and consumer_secret globally. (In a Rails application, this
could go in config/initializers/twitter.rb.)

Supported Ruby Versions

This library aims to support and is tested against the following Ruby
version:

Ruby 1.8.7

Ruby 1.9.2

Ruby 1.9.3

This library may inadvertently work (or seem to work) on other Ruby
implementations, however support will only be provided for the versions listed
above.

If you would like this library to support another Ruby version, you may
volunteer to be a maintainer. Being a maintainer entails making sure all tests
run and pass on that implementation. When something breaks on your
implementation, you will be personally responsible for providing patches in a
timely fashion. If critical issues for a particular implementation exist at the
time of a major release, support for that Ruby version may be dropped.

Additional Notes

This will be the last major version of this library to support Ruby 1.8.
Requiring Ruby 1.9 will allow us to removevarioushacks put in place to maintain
Ruby 1.8 compatibility. The first stable version of Ruby 1.9 was released on
August 19, 2010. If you haven't found the opportunity to upgrade your
Ruby interpreter since then, let this be your nudge. Once version 5 of this
library is released, all previous versions will cease to be supported, even if
critical security vulnerabilities are discovered.