Using the Basecamp API with Ruby on Rails

May 9th 2007

Note: This is an import of a popular article that I wrote some time ago about using the Basecamp API with Rails. The internet archive version is also still available and contains blog comments.

37 Signals released the API to Basecamp this weekend.

This tutorial will show you how to get started using it in your Rails applications. Don’t forget to enable API access on your account by logging in, clicking the Account tab, and checking the box in the API section.

Make a new rails app

rails basecamp

Copy the ruby wrapper file to the lib directory from http://www.basecamphq.com/api/basecamp.rb

Add the following at the bottom of config/environment.rb:

require 'basecamp'

Also ensure that all the relevant gems are installed:

sudo gem install xml-simple

Lets test this all works on the console:

script/console
session = Basecamp.new(beyondthetype.updatelog.com', 'username', 'password')
puts "projects: #{session.projects.length}"
projects: 1

All going well you should get the number of the project account listed.

Getting a list of all the message titles in our first project

session.message_list(session.projects.first.id).collect{|m| m.title}
  => ["Second post", "This is the first post"]

A list of all project message categories

session.message_categories(session.projects.first.id).collect{|c| c.name}
 => ["Assets", "Code", "Copywriting", "Design", "Miscellaneous", "Transcripts"]

A test post:

@project  = session.projects.first
@category = session.message_categories(@project.id).first
session.post_message(@project.id,
      { :title => "A test post using the Basecamp API",

        :body => "Testing 123",
        :category_id => @category.id})

If you check back in the Basecamp web based interface sure enough the message is listed. Sweet.

Lets extend this by creating a simple Rails application that lists all the messages in our project.

For the purpose of this exercise we will make use of Rails scaffolding. Create the table:

create_table "posts", :force => true do |t|
  t.column "title", :string, :limit => 200
  t.column "body", :text

  t.column "project_id", :integer, :default => 0, :null => false
  t.column "category_id", :integer, :default => 0, :null => false
end

script/generate scaffold Post

Edit app/controllers/posts_controllers.rb At the bottom of the controller add:

private 
  def basecamp_connect
     @basecamp = Basecamp.new('your_account.updatelog.com',

     'your_username', 'your_password')
  end

At the top
  before_filter  :basecamp_connect

 def list

    project  = @basecamp.projects.first  
    @posts   = @basecamp.message_list(project.id)
 end

 def show
   @post   = @basecamp.message(params[:id])

 end

In the views you will need to remove all reference to pagination, error_messages_for, and column names in the listing since the data that is returned from Basecamp is not the normal Rails model. All going well you will see your messages listed: Basecamp API with Ruby on Rails I’ll leave the updating and adding as an exercise for later but you get the idea.

So in summary this implementation is pretty crude but it’s a starting point. To get any kind of decent performance when using remote API’s caching of returned data is well worth looking at. Also you might want to consider putting the Basecamp login credentials in the main configuration file. On another note, I can certainly see some Rails plugins/engines popping up that will automate much of this process. What would be really nice is if you could do something as simple as create a model called posts and add the following line:

act_as_basecamp_message

This would take care of all the remote calls, caching and such like but behaves just like a normal Rails model. Actually this would be nifty for any remote API not just Basecamp. For example:

acts_as_remote_model :use => 'company.projectpath.com', :model => 'message'</code>

But that’s a topic for another day! Here are some further thoughts and ideas on how to use the Basecamp API:

Listing of Project milestones on a blog
Project analytics – frequency of posts, top poster, busiest project
Cleanup tools to remove or archive
Sync tools between Basecamp and existing applications
Gantt chart export to Basecamp
A portfolio site for your company using client and project data from BC e.g what we are currently working on
Copying or moving data from one project to another

If you found this article useful or have any questions please leave comments below. Thanks!

Make a new rails app

Related Links: