Using the Basecamp API with Ruby on Rails
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:
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'
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!
Related Links:
* Basecamp API doc
* Basecamp API Ruby Wrapper
* Basecamp API Forum
Posted by Martin on Wednesday, May 09, 2007
