Ruby Client for Remember The Milk

Author: Dave Copeland (davetron5000 at g mail dot com)
Copyright: Copyright © 2009 by Dave Copeland
License: Distributes under the Apache License, see LICENSE.txt in the source distro

Install

Note that the most up-to-date version of the gem is hosted at [www.gemcutter.org], so you’ll need a one-time setup if you aren’t already using Gemcutter as your primary source for gems.

# Only if you aren't using gemcutter yet
sudo gem install gemcutter
sudo gem tumble

# Once Gemcutter is setup
sudo gem install moocow

Overview

This is a very lightweight and easy-to-use client for [www.rememberthemilk.com]

require 'moocow'

rtm = RTM::RTM.new(RTM::Endpoint.new(your_api_key,your_secret))
rtm.token = user_token
response = rtm.tasks.getList
response.tasks.list.as_array.each do |list|
  # this is an RTM list of taskseries
end

Authorization

Authorization is a bit tricky, but you only need to do it one time. This example shows command line/desktop usage

rtm = RTM.new(Endpoint.new(your_api_key,your_secret))
auth = rtm.auth
url = auth.url
frob = auth.frob
# Send user to this URL
# They will authorize your app's api_key via the RTM website.  
# store the frob somewhere, you will need it
#
# When they return...
auth.frob=frob
rtm.token=auth.get_token
# store the token for all time

rtm.tasks.getList
rtm.groups.delete
rtm.tasks.notes.add

And so forth. Basically, you can call the RTM methods as if they were real methods.

Responses

As shown above, you can simply navigate the XML returned by method names. This uses Hash.method_missing and can be dicey, so you can also navigate a bit safer via

response = rtm.tasks.getList
response['tasks']['list'].as_array.each do |list|
  # this is an RTM list of taskseries
end

Note that for any element that you want to treat as a list, you must call as_array on it, to ensure that it gets turned into a list. The underlying HTTParty code doesn’t know if an XML element is supposed to be a list or just a singular.

Note that you can use Ruby-style conventions instead of camel-case, e.g. rtm.tasks.get_list

Timelines

Many methods require timelines; this is the way that RTM provides for undo-type features. If you don’t really care about this, or want it done for you, you can specify auto timeline creation:

rtm.auto_timeline=true
rtm.tasks.add(:name => 'My new task')
timeline = rtm.last_timeline

This will create a timeline for you, and use it to create the task. The list of methods that do not require timelines is used to determine if this is done, and is based on the RTM documentation at the time of this writing.

Basic Command Line

To verify and play with the RTM API, there is a command-line tool called rtm. It takes the following commands:

any: executes any RTM method
auth: Prints out the auth URL to authorize your api key/ruby client. Do not do this after getting a token
chktoken: Checks that your token is valid
help: Shows list of commands or help for one command
ls: Lists incomplete tasks
token: Gets your token; do this only once and put it in your api.yaml file

The easiest way to get started is to get your API Key and Secret from RTM and then:

rtm ls

This will init your api.yaml file

rtm auth

Go to this URL and authorize your API Key. Save the frob that is printed out

rtm token <<frob>>

This will authorize your app and print out your token. Edit api.yaml and add your token.

:token: <<your token>>

To verify:

rtm ls

This should list your incomplete tasks if all is well.

rtm any contacts.getList

Will print out a hashdump of what RTM returns for this method.