Last week I committed quite a substantial update to the monkehTweets library on Github (also available via riaforge.org).
For those who don't know, Twitter have been working to update their API in the first big update since it's launch, and v1.1 is the result of their work.
How Long Do I Have Left?
For all developers and applications currently using the previous versions of monkehTweets (and Twitter API v1 as a result) you have a rather generous amount of time to update your code and make the transition to the new API. Version 1 will be closed off and no longer available from the start of March 5th, 2013. (source: https://dev.twitter.com/docs/api/1.1/overview#Deprecation_of_v1.0_of_the_API)
The pre-v1.1 implementation of monkehTweets is still available via Github in it's own branch, which is available here should you need it: https://github.com/coldfumonkeh/monkehTweets/tree/1.3.2_v1.1/
Changes
There have been a number of changes to the API, including revised endpoints to reflect the new API version number (1.1), but most of these should fall under the radar of users and implementors of the monkehTweets library as it will manage these for you.
The biggest changes to the API update are as follows:
- All calls to the API require authentication (oauth)
- All requests and responses will be in JSON format
It is important to note at this stage that the instantiation and use of monkehTweets itself has not changed. It was developed to be easy to use and to open up the detailed API for all CFML developers without having to instantiate Java classes. This has not changed and you can still get up and running in seconds. The example code in the project download will help you get your application set up and posting tweets very quickly.
How has monkehTweets dealt with these changes?
The authentication process was easy to manage. For the small number of methods that were making un-authenticated method calls, these were amended to run through the function dealing with the OAuth authentication. From a user point of view, this will have little to no impact on your existing code. As the application / user needs to be authenticated and those details are stored in the monkehTweets object, this will be handled invisibly for you.
The formatting was a little more detailed to change. All of the methods in monkehTweets used to have an argument called 'format' which used to default to XML. This allowed users to select the response format of the data to process in their preferred manner. The format arguments have now been stripped from all method calls, and the remote URL endpoints for each method have been forced to use JSON. If you are using XML responses you WILL need to amend your code to handle the new return format.
Method Changes
The following functions have been removed from monkehTweets as they were no longer supported in the v1.1 API:
- addNotification
- blockExists
- endSession
- friendshipExists
- getAccountTotals
- getDailyTrends
- getLists
- getNoRetweetIDs
- getPublicTimeline
- getRetweetedToUser
- getRetweetsByMe
- getRetweetsByUser
- getRetweetsOfMe
- getRetweetsToMe
- getUserProfileImage
- getWeeklyTrends
- oauthRateLimitStatus
- rateLimitStatus
- removeNotification
- retweetedBy
- retweetedByIDs
- test
If your application uses any of the above methods, you will need to revise the code to remove them and amend any functionality that depends on them.
The following functions have been added to monkehTweets as new additions in the v1.1 API:
- closestTrends
- getApplicationRateLimitStatus
All other methods remain active and current. Any changes made to existing methods in the monkehTweets library have been done as quietly as possible so as not to impact the code and therefore the implementation of the code. Method names have not been changed where possible to make the transition easier for you to manage.
Error Handling
One of the biggest issues I had with the ever-evolving Twitter API and method parameters was managing the error handling, certainly when trying to accomodate for a number of response formats.
In the previous version of the package, the requested format was passed through to the sub-methods along with the response to correctly format the data and attempt to check for any error codes before returning to the user. The Twitter API error processing changed and the code was unstable, certainly when dealing with XML responses.
Whilst my original intention was to trap any errors and return a user-friendly error message back to the user / developer, in the latest release I have completely dropped this functionality. This was done primarily for two reasons:
- It was unstable due to numerous changes from Twitter and I feared that if they changed their error handling again it would cause more errors.
- Having just one response format now made this easier. JSON will be returned regardless of whether the request was a success or failure.
This now means that users and developers will need to catch any errors from the API themselves. To help with this, Twitter have a fairly detailed list of error response codes to watch out for: https://dev.twitter.com/docs/error-codes-responses
The example used on the site shows the error response in JSON format, and is a clear indication of what to watch out for:
{"errors":[{"message":"Sorry, that page does not exist","code":34}]}
More Information
For more information and clarification on the official changes to the Twitter API introduced in v1.1, please check out the API overview on the official documentation page: https://dev.twitter.com/docs/api/1.1/overview
Use monkehTweets?
Do you use monkehTweets? Has it saved you time, money, pain and stress? Let me know. I always look forward to seeing how people are using it in their applications.
If it really helped you, feel free to visit my Amazon wishlist and say thanks :)