There are two backwards-incompatible changes in this version:
-
When Twitter returns an error (or an HTTP error is generated because Twitter can't be reached), the body of the HTTP response will be returned in a tuple like {error, session_remotly_closed}. When Twitter rejects the OAuth credentials for a user, the tuple will be {oauth_error, "Body"}.
-
The Direct Message format for XML has changed, so there is now a separate message record, distinct from status, which is returned when accessing one of the Direct Message methods.
erlang_twitter is a simple gen_server based client to Twitter's API. It supports the entire Twitter API and all combinations of options including API method aggregation.
1> twitter_client:start().
{ok,<0.44.0>}
2> twitter_client:add_session("ngerakines", "ugottabejoking").
ok
3> twitter_client:call("ngerakines", status_friends_timeline).
[{status,"Sun Aug 10 05:41:49 +0000 2008","883056945",
"Watching \"Bait Shop\" starring Bill Engvall and Billy Ray Cyrus.",
"web","false",[],[],[],undefined}
{status, ...} | ...]
The module layout is relatively simple and self explanatory. Each of the Twitter API methods map directly to a module function. For example, the Twitter API "statuses/friends_timeline.xml" can be accessed using twitter_client:status_friends_timeline/4.
Each API method function has the same function parameters. They are a string representing the root API url, the login and password for the account and then a list of API method specific arguments. API methods that do not use certain arguments ignore them.
The status and user records as defined in twitter_client.hrl represent statuses and users as returned by API requests.
Ideally all API method functions are accessed through the gen_server API exposed by the module. The twitter_client:call/2 and twitter_client:call/3 functions are used for this purpose. The API method functions can also be accessed directly if you wish to bypass the twitter_client gen_server altogether.
To use the oauth functionality in erlang_twitter, you need the erlang-oauth library available here. Once you have your application's Consumer keypair (obtained from Twitter) and a Token and a Secret for your users, you can make OAuth requests to Twitter like
1> inets:start().
2> twitter_client:status_user_timeline("http://twitter.com/", Consumer, Token, Secret, []).
Note: User session management via add_session is not currently available.
This module can be used to make API requests on behalf of multiple accounts. Use the twitter_client:add_session/2 function to do so.
2> twitter_client:add_session("usera", "password").
ok
3> twitter_client:add_session("userb", "secret").
ok
4> twitter_client:call("usera", status_friends_timeline).
...
5> twitter_client:call("userb", status_friends_timeline).
...
This module supports a limited way to throttle API calls. Internally, it tracks a delay value and the last time an API call was made (regardless if it was successful or not). Using the twitter_client:delay/0 function will return the number of seconds you should wait before making the next API request.
NOTE: This functionality does not incorporate any server-side throttling. It is simply based on the last time an API call was made taking into account the delay value set. The delay value can be updated using the the twitter_client:set/2 function
1> twitter_client:set(delay, 2).
ok
It is a good idea to wait at least 1 second between every API request. Not only is it polite, but it increases your application's karma and will get you laid.
This module has gone through very light testing to verify Identi.ca support. Accessing an Identi.ca server's API can be done by setting the base_url setting for the client.
4> twitter_client:set(base_url, "http://identi.ca/api/").
ok
By default, the base_url is set to "http://twitter.com/".
Use make package-debian
and make install-debian
to build a .deb file for Debian deployment.
- Harish Mallipeddi
- Joshua Miller