/ 
WebService-RTMAgent-0.603
River stage one • 1 direct dependent • 6 total dependents
/ WebService::RTMAgent

NAME

WebService::RTMAgent - a user agent for the Remember The Milk API

VERSION

version 0.603

SYNOPSIS

$ua = WebService::RTMAgent->new;
$ua->api_key($key_provided_by_rtm);
$ua->api_secret($secret_provided_by_rtm);
$ua->init;
$url = $ua->get_auth_url;  # then do something with the URL
$res = $ua->tasks_getList('filter=status:incomplete');

...

DESCRIPTION

WebService::RTMAgent is a Perl implementation of the rememberthemilk.com API.

Calling API methods

All API methods documented at https://www.rememberthemilk.com/services/api/ can be called as methods, changing dots for underscores and optionnaly taking off the leading 'rtm': $ua->auth_checkToken, $ua->tasks_add, etc.

Parameters should be given as a list of strings, e.g.:

$ua->tasks_complete(
  "list_id=4231233",
  "taskseries_id=124233",
  "task_id=1234",
);

Refer to the API documentation for each method's parameters.

Return values are the XML response, parsed through XML::Simple. Please refer to XML::Simple for more information (and Data::Dumper, to see what the values look like) and the sample rtm script for examples.

If the method call was not successful, undef is returned, and an error message is set which can be accessed with the error method:

$res = $ua->tasks_getList;
die $ua->error unless defined $res;

Please note that at this stage, I am not very sure that this is the best way to implement the API. "It works for me," but:

  • Parameters may turn to hashes at some point

  • Output values may turn to something more abstract and useful, as I gain experience with API usage.

Authentication and authorisation

Before using the API, you need to authenticate it. If you are going to be building a desktop application, you should get an API key and shared secret from the people at rememberthemilk.com (see https://groups.google.com/group/rememberthemilk-api/browse_thread/thread/dcb035f162d4dcc8 for rationale) and provide them to RTMAgent.pm with the api_key and api_secret methods.

You then need to proceed through the authentication cycle: create a useragent, call the get_auth_url method and direct a Web browser to the URL it returns. There RememberTheMilk will present you with an authorisation page: you can authorise the API to access your account.

At that stage, the API will get a token which identifies the API/user authorisation. RTMAgent saves the token in a file, so you should never need to do the authentication again.

Proxy and other strange things

The object returned by new is also a LWP::UserAgent. This means you can configure it the same way, in particular to cross proxy servers:

$ua = new WebService::RTMAgent;
$ua->api_key($key);
$ua->api_secret($secret);
$ua->proxy('http', 'https://proxy:8080');
$ua->init;
$list = $ua->tasks_getList;

Incidentally, this is the reason why the init method exists: init needs to access the network, so its work cannot be done in new as that would leave no opportunity to configure the LWP::UserAgent.

PERL VERSION

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

PUBLIC METHODS

$ua = WebService::RTMAgent->new;

Creates a new agent.

$ua->api_key($key);

$ua->api_secret($secret);

Set the API key and secret. These are obtained from the people are RememberTheMilk.com.

$ua->verbose('netin netout');

Sets what type of traces the module should print. You can use 'netout' to print all the outgoing messages, 'netin' to print all the incoming messages.

$err = $ua->error;

Get a message describing the last error that happened.

$ua->init;

Performs authentication with RTM and various other book-keeping initialisations.

$ua->get_auth_url;

Performs the beginning of the authentication: this returns a URL to which the user must then go to allow RTMAgent to access his or her account.

This mecanism is slightly contrieved and designed so that users do not have to give their username and password to third party software (like this one).

@undo = $ua->get_undoable;

Returns the transactions which we know how to undo (unless data has been lost, that's all the undo-able transaction that go with the timeline that is saved in the state file).

The value returned is a list of { id, op, [ params ] } with id the transaction id, op the API method that was called, and params the API parameters that were called.

$ua->clear_undo(3);

Removes an undo entry.

PRIVATE METHODS

Don't use those and we'll stay friends.

$ua->sign(@params);

Returns the md5 signature for signing parameters. See RTM Web site for details. This should only be useful for the module, don't use it.

$ua->rtm_request("rtm.tasks.getList", "list_id=234", "taskseries_id=2"..)

Signs the parameters, performs the request, returns a parsed XML::Simple object.

FILES

~/.rtmagent

XML file containing runtime data: frob, timeline, authentication token. This file is overwritten on exit, which means you should only have one instance of RTMAgent (this should be corrected in a future version).

SEE ALSO

AUTHOR

Yves Rutschle

CONTRIBUTORS

  • Ed Santiago <ed@edsantiago.com>

  • Ricardo Signes <rjbs@semiotic.systems>

  • Yves Rutschle <CENSORED>

COPYRIGHT AND LICENSE

This software is copyright (c) 2008 by Yves Rutschle.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.