Twitter @Anywhere Javascript API exposed

So I have been working on some serious Twitter and Facebook integration on the client-side for a recent project. To do some of the things I wanted to do I needed to use the Twitter @Anywhere Javascript API. The only problem with using the Twitter @Anywhere API is that it is very thinly documented and not likely to be updated soon.

Being the enterprising fellow I am, I pulled down there main API Javascript code from Firebug and put it into Eclipse (with Aptana) highlighted the one line of code (there were no line breaks), did an Apple-Shift-F on the code (fix the syntax), and boom! I now had a nicely formatted Javascript file with the Twitter @Anywhere API. I won't publish it here as that is Twitter's property and I don't want to get into any trouble.

What I will talk about is some of the things I learned about how to use the @Anywhere API; some things that your really need to make it feasible to use at all, even just to test.

First major find was how to pass parameters through the @Anywhere API to the regular Twitter API. The current @Anywhere cheatsheet describes doing calls like:

User.current.homeTimeline()

That by default will only give you back the first 20 items in the current user's feed, it doesn't allow using a "since_id" or a "max_id" parameter to restrict what items are returned, and it doesn't let you do pagination of the returned results.

From looking over the code I noticed you could input options to the call by doing the following:

User.current.homeTimeline({count:200, rpp:3, since_id:171981, max_id:181981});

This would fire off a request to the regular Twitter API that looks like:

http://api.twitter.com/1/statuses/home_timeline.xml?count=200&rpp=3&since_id=171981&max_id=181981

Which is exactly what we want, now we can control what we get back with the same precision as the regular Twitter API.

The next thing I figured out was how to avoid using the type of statements that the Twitter @Anywhere API cheatsheet examples use. For example the cheatsheet uses stuff like this:

User.current.homeTimeLine().first(20).each(
    function(status) {
         alert(status.text);
    }
);

This is great when you want to do something atomically with each status you get back, but absolutely sucks when you want to know when you have completed going through all the statuses. The above example immediately returns, it is not synchronous, which makes it nearly impossible to know when it is done (maybe some closure could do it, but I couldn't figure it out).

To combat this I dug into the Twitter @Anywhere API further and found that I can also pass in options to put my own callback for success and error:

User.current.homeTimeline({count:200, rpp:3, since_id:171981, max_id:181981, success:my_success_method, error:my_error_method});

Now your callbacks will be called and you will see the "data" element passed in to your callback has an "array" element, which contains all the returned results. Now you can go through your results at your leisure, and know when you are done to fire off other methods.

That is pretty much all I have found out thus far, but it is enough to do quite a bit of work with the Twitter @Anywhere Javascript API. As always cheers and jeers in the comments...