LA Times Travel uses Twitter4R

LA Times Travel is now using Twitter4R (Ruby library for the Twitter API).

You can see they sent messages via the Twitter4R for a few hours today (2008-07-22) on their Twitter timeline before changing the Twitter4R configuration to not sure which library/application they are using (or just waiting to get Alex to approve their application source code).

Please let me know if you see Twitter4R sightings being used by other well known or cutting edge applications.

Twitter4R Development Releases

Over the last week or so I have been putting Twitter4R sources in GitHub and getting the on-the-fly GemSpec to work "safely" enough for GitHub servers. Tonight (June 30) I decided I would announce Twitter4R development micro-releases available only via the GitHub gem server. To setup your environment to install the latest development release of Twitter4R: the most complete Ruby client bindings for the Twitter.com REST API, please read HowTo: Install GitHub Development Releases

Official documentation will still exist through the official Rubyforge project site of Twitter4R, but any documentation related to current development tasks, features, bugfixes will now be documented on the Official Twitter4R GitHub Wiki.

If you want to keep an eye on the Git repository, feel free to watch the mbbx6spp/twitter4r GitHub repository.

Twitter4R v0.3.0

After Twitter.com added a few extra APIs for favoriting statuses in October, I finally got around to adding them to Twitter4R tonight. Since there is new functionality I have released it as version 0.3.0.

To install all you need to do is:

$ sudo gem install twitter4r

The Rubyforge mirrors might still be syncing if you are doing this soon after I post this message.

The changes to the library include:

• Added Twitter::Client#authenticate? method that is a lightweight way to verify a Twitter user's credentials
• Favorites: allows Twitterers to add statuses to their favorites, list all their current favorites and remove any statuses from the list.

Example code for verifying a user would look like:

gem('twitter4r', '>=0.3.0')
require('twitter')

client = Twitter::Client.new
unless client.authenticate?("macdeveloperthatlovesleopard", "iamasciolists")
  puts "Password does not describe user well!"
end

if client.authenticate?("developerthatdoesnotpretendtobegraphicdesigner", "seriousdevelopernotfakestevejobswannabe")
  puts "Password does describe user well!"
end

Example code for using the favorites API:

gem('twitter4r', '>=0.3.0')
require('twitter')
require('twitter/console')

client = Twitter::Client.from_config('some/path.yml')
statuses = client.favorites
ids = statuses.collect {|s| s.id }
# clean favorites list by deleting
statuses.each {|s| client.favorite(:remove, s) }

# now add back first status id from original favorites list
client.favorite(:add, ids[0])

Enjoy!

The Democratic debate, Ann Coulter and cryptographic utilities for Ruby application developers

An unlikely trio, but...

After watching the flip flop of Clinton in the Democratic debate, the subsequent carcass ravaging by her competition, UFO spotting by spock (aka Kucinich) and two great stinging one-liners from Joe Biden about the presidential [dis]qualification of candidate 911, I stumbled across the infinitely dim and unimpressive Ann Coutler. She was attempting to justify yet another deliberately outlandish statement she made last week, a desperate bid to remain in the limelight to which she is so addicted.

At this point, I remembered I wrote a RubyGem a few weekends ago that might be able to decrypt these events and make sense of it all (well maybe!?).

A few weekends ago I released metafusion-crypto as a Ruby Gem. I hadn't announced it yet as it got lost in the shuffle of some personal matters that forced me to take five days off work unexpectedly. So here is the belated introduction to that small, humble Gem.

This metafusion sub-project is basically just two utility classes: Metafusion::Crypo::PrivateKey and Metafusion::Crypo::DigitalSignature for application developers that don't want to worry about twiddling bits. To install you only need to do the following:

$ sudo gem install metafusion-crypto

An example of DigitalSignature usage might be:

require 'metafusion/crypto'

priv_key = Metafusion::Crypto.generate_key_pair
# this returns OpenSSL::PKey::RSA object into priv_key

include Metafusion::Crypto
sig = DigitalSignature.from_keys('rsa_key.pub', 'rsa_key')
original_text = "my clear text message"
crypted_text = sig.encrypt(original_text)
plain_text = sig.decrypt(crypted_text)
puts "It worked - let's celebrate!" if original_text == plain_text

An example of PrivateKey usage might be:

include Metafusion::Crypto
pkey = PrivateKey.new('mypassphrase')
original_text = 'Yo yo yo.  What up dog?'
crypted_text = pkey.encrypt(original_text)
plain_text = pkey.decrypt(crypted_text)
puts "Let's roll and celebrate - it worked" if original_text == plain_text

I look forward to application developer's feedback.

I promise to return to the agile anti-pattern "series" soon.

Update: Since two people asked, I have stuck to my tradition of releasing with only 100% C0 code coverage of the project's RSpec examples.

Twitter4R Announcements

First off I have been meaning to post an entry letting people know of a recently released Rails application written by Sergio Santos called TwitterNotes that is using the Twitter4R gem.

Thanks Sergio (and anyone else that worked on the project - sorry if I left you off).

Also Sergio emailed yesterday requesting message paging support with a suggested patch (thanks for contributing back - muchas gracias). This evening I released Twitter4R version 0.2.5 that incorporates the necessary code changes for this support.

What does this mean?

Previously you would have only been able to get the last 20 sent/received direct messages from the Twitter4R bindings doing something like the following:

messages = client.messages(:sent)

Now you can request specific pages like so:

messages = client.messages(:sent, :page => 2)

The same is true for the :received case.

To install the Twitter4R RubyGem simply run the following in your terminal/console:

$ sudo gem install twitter4r

Give the Rubyforge mirrors a few hours to sync if you are only getting Twitter4R v0.2.4.

Thanks and enjoy!

Twitter4R v0.2.4 Released

Version 0.2.4 of Twitter4R was released last night with the main change that makes the library much easier to use in Ruby on Rails applications.

To install/update Twitter4R v0.2.4 just use the following command: sudo gem install twitter4r

For more information on how to integrate Twitter4R with Rails see the following links:

• Twitter4R on Rails [DevChix blog post]
• TweetApp: Twitter4R on Rails [reference application]
• Twitter4R on Rails Screencast
• Twitter4R RDoc

Twitter4R v0.2.3 Released

As promised earlier this week Twitter4R v0.2.3 made it out this weekend.

Twitter4R v0.2.3 has just been uploaded to Rubyforge in Ruby Gem, tgz and zip formats. It may take up to several hours for the Rubyforge download mirrors to sync, so you may not be able to download it for a while.

To upgrade/install using Ruby Gems:
$ sudo gem install twitter4r

I am in the process of updating the project website. So bear with me while I take care of this.

Release Notes:

• Fixed defect #31 such that passing string screen name as for user argument is handled correctly.
• Fixed #30 typo: respond_to -> respond_to?
• Added relevant exception handling for #message(:post, ...) case #32
• Add ability to pass in Twitter::User object to Twitter::Client#user(...) #33
• Added stats Rake task
• Updated RDoc for Twitter::Client#user to warn against using it to get followers of authenticated user and updated ArgumentError raising logic as per #29.

Enjoy!

Twitter4R v0.2.2 Released

As solo already noted in the comments for the Twitter4R v0.2.1 Released blog entry from yesterday, version 0.2.2 is already here:)

I usually wait 4 hours before I blog about it to let the Rubyforge gem servers sync.

Changes in the version 0.2.2 release include:

• Fixed URI paths for user, messaging and friendship APIs (#25)
• Added action checks for Twitter::Client methods: #user, #my, #message, #messages, #status, #timeline, #friend (#26)
• Added 'source' configuration documentation.
• Added missing attributes for Twitter::User (#28)

The most notable thing is that I add the protected and profile_image_url attributes to the Twitter::User model class, which were missing previously.

Twitter4R v0.2.1 Released

To install/update Ruby gem use:
sudo gem install twitter4r
OR
sudo gem update twitter4r
Note: It may take some hours before the Rubyforge mirrors are in sync.

The ‘source’ feature was added to Twitter v0.2.1 such that in the web interface Twitter users can see which application the messages were sent from. The default is ‘twitter4r’ with link ‘http://twitter4r.rubyforge.org’. You can change this, but you will also need to contact Twitter developers (not Twitter4R) to set it up for you on the server side. To set relevant client configuration in Twitter4R you can do the following:

require('rubygems')
gem('twitter4r', '>=0.2.1')
require('twitter')

Twitter::Client.configure do |conf|
  conf.source = 'mysourceidfromtwitter'
end

Remember you will need to contact the Twitter developers to setup a source id and url with them before the above code snippet will start working.

Enjoy!

Twitter4R v0.2.0: Friendship API

After a week I realized I had not yet written about the Friendship API in Twitter4R and it is one of the simpler the parts of the core library.

Below shows some code to add and remove a friend:

require('rubygems')
gem('twitter4r', '>=0.2.0')
require('twitter')

client = Twitter::Client.new(:login => 'mylogin', :password => 'mypasswd')
# we can add a friend by using their unique integer id or user object.
screen_name = 'myfriend'
user = Twitter::User.find(screen_name)
id = user.id

# Like any of the following....
client.friend(:add, user)
client.friend(:add, id)

# We can also use any of the following APIs to do exactly the same thing...
client.friend(:remove, user)
client.friend(:remove, id)

See related Twitter4R RDoc.

Twitter4R v0.2.0: Extras API

There are a couple of miscellaneous features in Twitter4R that I wasn't comfortable officially supporting like the featured users method in the Twitter REST API that is documented to do one thing and implemented to do another by the actual Twitter developers. Obviously I don't control what the Twitter developers do, so while I wanted to support this REST API in the library to achieve 100% Twitter REST API coverage I also wanted to emphasize that if the Twitter REST API implementation changes to work as documented then Twitter4R may not work well or at all for this method. To get an Array of Twitter::User objects that represent Twitter's current featured users we would write code like:

require('rubygems')
gem('twitter4r', '0.2.0')
require('twitter')

# Now we must include this extra file import or we will get a NoMethodError
require('twitter/extras')

client = Twitter::Client.new
users = client.featured(:users)

Also in the Twitter4R Extras API is a class helper method added to Twitter::Client called from_config which takes up to two arguments. Here is an example:

require('rubygems')
gem('twitter4r', '0.2.0')
require('twitter')

# I have a 'twitter.yml' file in subdir 'config' that I will load credential from.
# This feature of Twitter::Client is in the Extras API and you need to require
# twitter/console to access it.
require 'twitter/console'
config_file = File.join(File.dirname(__FILE__), 'config', 'twitter.yml')
twitter = Twitter::Client.from_config(config_file)

# By default the from_config method selects the credentials defined
# for the 'test' environment.  The twitter.yml file will look something like this:
#  test:
#    login: mylogin
#    password: mypasswd
# If, however, we wanted another environment's credentials to be used we pass that 
# in as the second argument to from_config like so...
twitter = Twitter::Client.from_config(config_file, 'dev')

Again here is a link to the Twitter4R v0.2.0 RDoc.

Twitter4R v0.2.0: User API

The User API provides an easy Ruby API that maps onto a less consistent Twitter REST API, which is good news for Twitter4R users:)

The following example code snippet shows how you would use the Twitter4R User API:

require('rubygems')
gem('twitter4r', '0.2.0')
require('twitter')

# I have a 'twitter.yml' file in subdir 'config' that I will load credential from.
# This feature of Twitter::Client is in the Extras API and you need to require
# twitter/console to access it.
require 'twitter/console'
config_file = File.join('config', 'twitter.yml')
twitter = Twitter::Client.from_config(config_file)

# Gets the Twitter::User object for user with screen name otherlogin.
user = twitter.user('otherlogin')
# Gets an Array of Twitter::User objects that represent the friends of user 
# with screen name otherlogin.
friends = twitter.user('otherlogin', :friends)

# Gets the Twitter::User object for the user we used to authenticate above
# using the Twitter::Client.from_config method in the Extras API above.
me = twitter.my(:info)

# Gets the Array of Twitter::User objects that represent the followers of 
# the user whose credentials were used to authenticate with the Twitter service.
myfollowers = twitter.my(:followers)
# The same can be done for friends, i.e.
myfriends = twitter.my(:friends)

# Alternative we can use the equivalent Model APIs like so....
myfollowers = me.followers
myfriends = me.friends

Hope you find this helpful. If you want to learn more about the User API you should consult the Twitter4R v0.2.0 RDoc.

Twitter4R v0.2.0: Messaging API

Probably one of the more recent additions to the Twitter REST API has been that of direct messaging. In the Twitter web interface we were introduced to the supported construct of direct messaging only a couple of months ago. The Messaging API in Twitter4R provides access to these new supported features via two instance methods on the Twitter::Client class: #message and #messages.

Below we can see an example of a common non-trivial usage of this API:

gem('twitter4r', '>=0.2.0')
require('twitter')

client = Twitter::Client.new(:login => 'mylogin', :password => 'mypassword')
received_messages = client.messages(:received)
# Now do whatever it is you wish to do with the Array returned and assigned to received_messages.
# It is an Array of Twitter::Message.  Twitter::Message has the following attributes:
# * sender (Twitter::User)
# * recipient (Twitter::User)
# * text (String)
# * created_at (Time)

new_message = client.message(:post, 'I am addicted to Twitter', 'myfriendslogin')
# Note: if we had a handle to our friend's Twitter::User object we could substitute that object
# for the screen name screen given (i.e. 'myfriendslogin' in the above example).  This would 
# look like:
#  new_message = client.message(:post, 'I am addicted to Twitter', user)

# Now we realized sending that message was a big mistake, so we try to delete is quickly:
deleted_message = client.message(:delete, new_message)

To find out more about the Messaging API of Twitter4R visit the v0.2.0 RDoc and select the examples/messaging.rb link from the top left frame.

Also note that you can create new direct messages via the Model API of Twitter4R as well.

Happy direct messaging on Twitter using Twitter4R.

Twitter4R v0.2.0: Model API

For those that are familiar with the ActiveRecord API, the Model API of Twitter4R should feel fairly natural for you. Currently the raw Twitter REST API inherently exposes three types of models:

• Status
• User
• Message

These model classes are available via the Twitter4R classes Twitter::Status, Twitter::User and Twitter::Message respectively. What you will notice on these classes is that they have the familiar find and create class methods that behave almost identically to ActiveRecord::Base subclasses (or models as we call them in Rails applications). There is one difference, due in part to the slightly different way "connections" to the Twitter4R "datasource" is handled. So below is a non-trivial example of using these ActiveRecord style methods:

gem('twitter4r', '>=0.2.0')
require('twitter')

client = Twitter::Client.new(:login => 'mylogin', :password => 'mypassword')
# I want to post a new status to my timeline, which can also be do by:
#  client.status(:post, 'My new status message')
status = Twitter::Status.create(:client => client, :text => 'My new status message')

user = Twitter::User.find('dictionary', client)
message = Twitter::Message.create(:client => client, :recipient => user, :text => 'canadaphile')

What we see here is very similar to ActiveRecord style models, but not quite. In the find method invoked on Twitter::User above we supplied a second argument, which is the client (the client context or "connection") object. We also make sure to pass in a :client key-value pair in each create method called above. Without it an ArgumentError would be raised by each create call.

A few notes:

• Twitter::User does not define a meaningful create method since Twitter doesn't allow the creation of new user account via their REST API
• Twitter::User model has some class and instance helper methods, which are described more in the RDoc (see link below)

See the v0.2.0 RDoc for Twitter4R and select the examples/model.rb link from the top left frame.

Twitter4R v0.2.0: Status API

The Status API deals with access to single status objects on the Twitter server. Since "updating" (in the traditional sense) a status in Twitter is non-existent (you update your timeline with a brand new status, but you cannot edit individual status text after created), Twitter4R provide a CRD-style interface (rather than true CRUD-style).

For example, to post a new status to your timeline you might write code like the following:

gem('twitter4r', '>=0.2.0')
require('twitter')
client = Twitter::Client.new(:login => 'mylogin', :password => 'mypassword')
status = client.status(:post, 'Learning the Twitter4R Status API in 60 seconds.')

To retrieve the full status object (Twitter::Status instance - see Twitter4R Model API documentation) given a unique status ID you can code:

# Assume code in previous code snippet
status = client.status(:get, 140684282) # => should be announcement status of Twitter4R v0.2.0 release
# Now you can query the attributes of the status like...
puts "#{status.user.screen_name}: #{status.text} @ #{status.created_at}"

To delete the status we initially posted above (or any other status of yours that you have a handle to (a handle can be just the unique integer status ID or the status object itself) we can code:

# Again assume code from first code snippet above...
client.status(:delete, status) # here we can pass in the full object or just the id, it doesn't matter.  Same as in #status(:get, ...) case.

Upgrading from 0.1.x

To upgrade from Twitter4R v0.1.x you probably need to replace code like:

client.update('My status message text')

With code like the following:

client.status(:post, 'My status message text')

There were no APIs in Twitter4R v0.1.x for the single status :get and :delete use cases.

Twitter4R v0.2.0: Timeline API

The Timeline API segment of Twitter4R provides access to the REST API that deals with public, friend and [public] user status timelines. For example, to get an Array of statuses representing your own timeline on Twitter all you would need to type was:

gem('twitter', '>=0.2.0')
require('twitter')
client = Twitter::Client.new(:login => 'mylogin', :password => 'mypassword')
timeline = client.timeline_for(:me)

If your timeline is public and you do not need to invoke any authenticated methods, you do not need to pass in login/password credentials to the Twitter::Client constructor, just Twitter::Client.new is all that is needed.

Other than the :me timeline, the following are available:

• :public - returns the public timeline on Twitter (last 20 statuses)
• :friends - returns a timeline of all your friends' statuses
• :friend - returns a timeline of one particular friend
• :user - returns timeline of one particular user

Different options are available with each of the timelines described above. To read more consult the Twitter v0.2.0 official RDoc documentation.

Upgrading from 0.1.x

If you are upgrading from Twitter4R v0.1.x you will probably have code that looks similar to the following:

client = Twitter::Client.new(:login => 'mylogin', :password => 'mypassword')
timeline = client.public_timeline

All you will need to do is change the last (second) line above to:

timeline = client.timeline_for(:public)

Twitter4R v0.2.0: Configuration API

The Configuration API allows applications using Twitter4R configure static connection options such as:

• connection protocol (e.g. HTTP and SSL)
• host name and port (good for testing or if the Twitter REST API moved to a different subdomain)
• proxy settings (i.e. proxy host, port, username and password)
• user agent identifier
• X-Twitter-Client* HTTP headers for Twitter's internal usage analysis

This API intentionally tries to look like the Rails initializer/configuration API:

require('rubygems')
gem('twitter4r', '0.2.0')
require('twitter')

Twitter::Client.configure do |conf|
  # We can set Twitter4R to use :ssl or :http to connect to the Twitter API.
  # Defaults to :ssl
  conf.protocol = :ssl

  # We can set Twitter4R to use another host name (perhaps for internal
  # testing purposes).
  # Defaults to 'twitter.com'
  conf.host = 'twitter.com'

  # We can set Twitter4R to use another port (also for internal
  # testing purposes).
  # Defaults to 443
  conf.port = 443

  # We can set proxy information for Twitter4R
  # By default all following values are set to nil.
  conf.proxy_host = 'myproxy.host'
  conf.proxy_port = 8080
  conf.proxy_user = 'myuser'
  conf.proxy_pass = 'mypass'

  # We can also change the User-Agent and X-Twitter-Client* HTTP headers
  conf.user_agent = 'MyAppAgentName'
  conf.application_name = 'MyAppName'
  conf.application_version = 'v1.5.6'
  conf.application_url = 'http://myapp.url'
end

If using Twitter4R (open source Ruby library for Twitter REST API) in a Rails application I would recommend adding the necessary Twitter4R configuration code in config/twitter.rb then including it in the config/environment.rb file to keep configurations separate.

Upgrading from 0.1.1

In Twitter4R v0.1.1 you could configure protocol, server host, server port and proxy settings using the following code:

Twitter::Client.conf(
  :ssl => true, 
  :port => 443, 
  :proxy_host => 'myproxy.host', 
  :proxy_port => 8080)

This API no longer exists, so if upgrading to Twitter4R 0.1.1 you will need to change the above to something like the following:

Twitter::Client.configure do |conf|
  conf.protocol = :ssl
  conf.port = 443
  conf.proxy_host = 'myproxy.host'
  conf.proxy_port = 8080
end

This change shouldn't be too painful for people I hope.

Please refer to the Twitter4R v0.2.0 RDoc for more information.

Twitter4R 0.2.0 Release

It's been almost two weeks, but Twitter4R had some major refactoring and updating between 0.1.1 and 0.2.0. So I hope you will think the wait was worth it. As usual you can grab the latest Ruby Gem (once all Rubyforge mirrors have synced) with: sudo gem install twitter4r.

I am still in the process of pushing out the new Ruby Gem to Rubyforge and updating the website for the project, but the release is code complete.

Some changes are quite significant in some areas. The basic idea of this release (0.2.0) was to cover the official published Twitter REST API 100% and remove some of the clutter the first two releases of Twitter4R introduced partly due to mirroring Twitter's inconsistent API. In the same fashion as both previous releases of Twitter4R, version 0.2.0 has 100% C0 code coverage via RSpec specifications.

I separated out Twitter4R library into various API segments:

• Configuration
• Friendship
• Messaging
• Model
• Status
• Timeline
• User
• Extras

I will write a blog entry as an introduction to each segment over the next couple of days. In the meantime I will finish publishing the new website documentation and leave you with the RDoc for version 0.2.0.

Updates:

• New entry: Twitter4R v0.2.0: Configuration API
• New entry: Twitter4R v0.2.0: Timeline API
• New entry: Twitter4R v0.2.0: Status API
• New entry: Twitter4R v0.2.0: Model API
• New entry: Twitter4R v0.2.0: Messaging API
• New entry: Twitter4R v0.2.0: User API
• New entry: Twitter4R v0.2.0: Extras API
• New entry: Twitter4R v0.2.0: Friendship API

Twitter4R 0.1.1 Released

Twitter4R, the open source Ruby project for the Twitter REST API, version 0.1.1 has been released this afternoon as a Ruby Gem. It may take a little time for the new Gem to appear on the Rubyforge gem servers, but once replicated to all mirrors you should be able to do the following:

require 'rubygems'
gem 'twitter4r', '0.1.1'
require 'twitter'

client = Twitter::Client.new(:login => 'mylogin', :password => 'mypassword')
timeline = client.public_timeline
timeline.each do |status|
puts "#{status.user.screen_name}: #{status.message}"
end


This will get you started. Changes from 0.1.0 to 0.1.1 include:

1. Addition of proxy support
2. Addition of SSL support
3. Migration from RSpec 0.8.2 to 1.0.x specifications

For proxy support you can do the following:

require 'rubygems'
gem 'twitter4r', '0.1.1'
require 'twitter'

Twitter::Client.config(:proxy_host => 'myproxy.host', :proxy_port => 8080)
# continue using Twitter4R API as above.

Or if you have a proxy server that requires authentication, you can do the following:

Twitter::Client.config(:proxy_host => 'myproxy.host', :proxy_port => 8080, :proxy_user => 'myproxyuser', :proxy_pass => 'myproxypass')
# continue using Twitter4R API as above.


To force Twitter4R to use SSL, we would write the following configuration code before using the client API:

Twitter::Client.config(:ssl => true, :port => 443)


Enjoy!

Twitter4R Revamp

While nothing has yet to be release for Twitter4R since version 0.1.0, it has not be standing still. A number of changes will be released within the next few business days.

Firstly, I will be releasing Twitter4R 0.1.1 with just two public API changes (and one internal change):

• [PUBLIC] SSL support
• [PUBLIC] Proxy support
• [INTERNAL] Migration from RSpec 0.8.2 to 1.0.x

Secondly, I will also be releasing Twitter4R 0.2.0 very soon after 0.1.1, which will contain a number of API changes. These changes are mostly documented in the comments of ticket #6 in Twitter4R's Retrospectiva project. I plan writing much more RDoc documentation for 0.2.0 and subsequent 0.2.x releases. Lack of documentation was a problem with the 0.1.0 release.

The reasoning for the quick succession of releases of Twitter4R is so that 0.1.x versions can have the same public API, whereas 0.2.x signifies a change in API to allow us to cover more of the Twitter REST API without cluttering the Ruby API too much.

A major reason for the API revamp was to hide some of the very unRESTful and asymmetric things the Twitter team have exposed in their public API. If any of the Twitter team are reading this, I recommend RESTful Web Services.

I admit to dropping the ball on the next release of Twitter4R gladly, because it is true. I violated the first rule of agile development: Do not bite off more than you can chew!

I apologize and will learn from it. Thanks for your patience.