Ive been having a lot of fun over the weekend developing my own ColdFusion CFC wrappers to interact with the Twitter API (Application Programming Interface) – yes, I’m a geek.
Introducing monkehTweets
monkehTweets is the (rather catchy, I think you’ll agree) name of the CFC wrapper I have developed.
I must admit, I was surprised at how easy (and fun) the Twitter API itself is. It’s very easy to follow and simple to use. Having developed wrappers for various external APIs in the past, so far the Twitter API has been the most enjoyable to write for.
So, what’s included?
The wrapper itself contains 13 ColdFusion components. Eleven of these components deal specifically with a particular section/group of methods available through the Twitter API. These 11 components are:
- account
- blocks
- direct_messages
- favorites
- friendships
- lists
- notifications
- saved_searches
- stauses
- trends
- users
An abstract ‘base’ class is included that holds common utility functions used throughout the above 11 components.
Finally, there is the monkehTweet component itself, which is the user-facing façade, providing access to the ‘sub’ components. There are 70 methods open to the user/developer to access the API through the monkehTweet façade object, each one directly relating to an existing method within the Twitter API.
Instantiating the façade
The monkehTweet component is the only object required to be instantiated by the user, as follows:
objMonkehTweet = createObject('component',
'com.coldfumonkeh.monkehTweet').init('username','password');
The constructor method only requires two parameters; the Twitter username and account password respectively. These are persisted throughout the CFC package and included in every other component where required to make authenticated calls to the API service.
Running a simple call to obtain user details can be achieved like so:
objMonkehTweet = createObject('component',
'com.coldfumonkeh.monkehTweet').init('username','password');
// make a call to get user details and return data
result = objMonkehTweet.getUserDetails(id='coldfumonkeh');
Making the most of the REST
The Twitter API does it’s best to conform to the principles of Representational State Transfer (REST). The API itself allows for the data to be returned in a total of four MIME types, namely XML, JSON and the RSS and Atom specifications.
Each calling function within monkehTwitter cfc is very well documented in terms of hint attributes, and will let you know which formats are available for that particular method. Most methods generally support only XML or JSON, while a handful accept a combination of all four, and a few accept all four options.
In an effort to simplify the ability to switch file extensions, each calling method has an extra non-required argument (‘format’) which defaults to ‘XML’. Changing this value to another allowed extension when making a request to the API will ensure you retrieve the response back in the required format.
For example, making a call to the getLists() method accepting all default arguments:
// get all lists assigned to me, using default XML format result = objMonkehTweet.getLists();
This results in the output of XML formatted data, as shown in the example snippet below.
<?xml version="1.0" encoding="UTF-8"?> <lists_list> <lists type="array"> <list> <id>6651154</id> <name>Coldfusion</name> <full_name>@coldfumonkeh/coldfusion</full_name> <slug>coldfusion</slug> <description>ColdFusion developers</description> <subscriber_count>0</subscriber_count> <member_count>1</member_count> <uri>/coldfumonkeh/coldfusion</uri> </list> .... </lists> </lists_list>
Running the same method call, we can switch the ‘format’ parameter to ‘JSON’ like so:
// get all lists assigned to me, using JSON format result = objMonkehTweet.getLists(format='JSON');
The change in format request has been passed through to the API and the returned data is in JSON format, as per the example snippet below:
{"name":"Coldfusion","full_name":"@coldfumonkeh\/coldfusion",
"subscriber_count":0.0,"description":"ColdFusion developers",
"id":6651154.0,"slug":"coldfusion","mode":"public",
"member_count":1.0","uri":"\/coldfumonkeh\/coldfusion"}
Working with the output
So, you can see it really is very easy to pull the data back from the API in a workable ‘string’ format.
What if you wanted to work with or view the structural information of the returned data? For example, you might prefer to work with XML once it has been parsed, or JSON may be easier to work with if you can see it in a structural format. monkehTweets has been tweaked to allow for ease of use, and has taken this into consideration.
The intial instantiation method for the monkehTweet cfc accepts a third, non-required boolean parameter called ‘parseResults’. Set to false by default, if set to true, the returned data from any called method will be converted using XmlParse() for XML, RSS and Atom, and DeserializeJSON() for any JSON responses, converting the data into a struct or an array of structs.
For example, let’s run the getUserDetails() method once more, but let’s set the parseResults parameter to true for both the XML and JSON requests:
// instantiating the facade, but this time
// requesting structural data response
objMonkehTweet = createObject('component',
'com.coldfumonkeh.monkehTweet').init('username','password',true);
// make a call to get user details and return data in XML format
result = objMonkehTweet.getUserDetails(id='coldfumonkeh');
// instantiating the facade, but this time
// requesting structural data response
objMonkehTweet = createObject('component',
'com.coldfumonkeh.monkehTweet').init('username','password',true);
// make a call to get user details and return data in JSON format
result = objMonkehTweet.getUserDetails(id='coldfumonkeh',format='json');
I want it. Where can I get it?
Right here: monkehTweets.riaforge.org
The API wrapper has been released as an open-source package available to download from the riagforge.org library.
I hope that you download it, try it out and (fingers crossed) use it in a project. Let me know how you get on.
24 Comments on "monkehTweets ColdFusion Twitter CFC"
Hi there monkeh..
I have downloaded your code and started using it, it works really well and really suprisingly easy to implement..
Thing is, I want to allow users to sign into my site using twitter…obviously I could vallidate the twitter name and password passed to your monkeh cfcs, but im guessing that this is not legit as the authentication would need to occur on twitters site not mine…..
Any ideas? Thanks
Thanks for writing this, I was searching everywhere for something similar, but this has proven to be just as helpful.
Very helpful stuff here, and I’m extremely grateful for your work. I have been successfully using several functions in monkehTweets, but I can’t get getSearchByID or any of the search calls to work, except for the one that pulls the ids themselves. The returned output is consistently the html content of Twitter’s login page.
Didn’t know if this was a known issue or, god forbid, I am doing something wrong.
If you get a chance to respond, it would be much appreciated.
Best,
Kent
@eyemkent – thanks for your comment.
I’m currently working on site that has twitter blocked, but I will look into it as soon as I have access again
Matt -
Thanks so much for the quick response. Personally, not having access to Twitter doesn’t sound like a bad thing.
Let me know if you have a chance to check it out.
Best,
Kent
@eyemkent –
I know what you mean. Productivity suddenly increases tenfold without it!
I’m able to get the getSavedSearches() and getSearchByID() methods working. Can you let me know what methods you’re having trouble with? Send me the details and we’ll get it resolved.
Matt,
Been using monkehTweets on a couple of sites and it works perfectly, however I am just trying to implement them on a new site and when I run the initial monkehTweet.init(u,p) I get an error along the lines of:
value returned from init is not of type com.coldfumonkeh.monkehTweet
I have set it up the same as in the past, with a com folder in the webroot and then the coldfumonkeh folder in the com folder.
The only difference I can see is that I am using a mapping for other components in the app. Could this be interfering with the return? Is Coldfusion expecting a returntype of ‘mymapping.com.coldfumonkeh.monkehTweet’?
What happens if you add a this.mappings call in your application.cfc? Does it break monkehTweets for you?
Cheers,
Dave
Hi Dave
Thank you for your comment, and it’s always great to hear from people using the wrappers.
II must say that i haven’t had any issues with clashes between the returnType specified in the init method (com.coldfumonkeh.monkehTweet) or any per-application mappings.
Feel free to email me directly and we’ll get to bottom of it together if you’re still having any issues.
Hello
I get the following error;
401 Unauthorized – Authentication credentials were missing or incorrect.
// instantiating the facade, but this time
// requesting structural data response
objMonkehTweet = createObject(‘component’,
‘com.coldfumonkeh.monkehTweet’).init(‘fccnuland’,’12345678′,true);
// make a call to get user details and return data in XML format
result = objMonkehTweet.getUserDetails(id=’coldfumonkeh’);
Hi Frank
thanks for your message.
Twitter have now removed the basic authentication protocol, which was built into monkehTweets, and have replaced it completely with the oAuth protocol, which is the reason for the errors.
I’m updating the library now, and will release the revised packages as soon as possible.
Apologies to everyone for any inconvenience caused.
Looking forward to checking out an update for oAuth! Thanks!
Any news on the update to monkehTweets to support oAuth? Got a few sites that are using it and would be nice to get them up and running again. If you need any help testing it, give me a yell @phipps73
Hey Matt,
awesome working with this twitter wrapper,
i have been using it a lot ! it works like a charm !
when you will be releasing a new version with oAuth enabled?
thank you for your time,
Hi guys
I sincerely apologise for any one who’s been stuck without the revised OAuth version of monkehTweets.
I’m almost finished with the revision, and hope to have it released over the next few days. I’ve been snowed under with other projects and trying to wrap my head around OAuth at the same time.
It’s been ‘fun’ to get it integrated, but i have it working now after many headaches and pots of coffee. *cough* Amazon wishlist *cough*
Has anyone tried to delete a status? on the deleteStatus and retweet functions there’s a syntax error referencing arguments.id, which perhaps should be arguments.statusID. When I corrected, it has since dropped me down a different rabbit hole returning a 404 checkStatusCode. Anyone else run into this? If so, can you help me out on the fix?
Hi Jen
thanks for your comment. I’m looking into the current release again this evening. A few more gremlins to iron out, i see. I’ll amend the issues and let you know when a fix is out, which should be by Monday at the latest.
Great – thank you so much, Matt. Have a great weekend!
-Jen
@Jen – version 1.2.4 of monkehTweets has been released which addresses the issue you were having with the argument parameters.
In the latest versions of monkehTweets (after the OAuth requirements were enforced), all parameter names HAD to match the actual parameters expected by the API. In this instance, some of the arguments still held the original naming conventions from the earlier version of the component (prior to OAuth), which were given slightly more user-friendly names.
These were missed when updating the component, which then caused your issues.
Apologies for any inconvenience caused.
The parseResults parameter of the MonkehTweet.init method doesn’t work for me. I wrapped the result in a DeserializeJSON() function and that did something, added curly braces and escaped a lot of characters. IsStruct returns ‘NO’ StructKeyArray throws an error (trying to reference a string as a structure.) I’m getting back the correct results, just not getting a struct. IsJSON() returns ‘YES’ regardless of the parseResults parameter. I’m on cf 9.0.0… I’ll check when I get home on cf 9.0.1
Great tool in any event. Thanks.
Just updating a site to use the latest (1.2.4) version and I have created the consumer key/secret on the twitter api site and run through the authorise process to get the access token/key however when I try and run getUserTimeline() I get a 401 error (Authentication credentials were missing or incorrect). If I run verifyCredentials() using the same details I get back a 200 response along with details of the twitter account which suggest that I have the correct oAuth settings. Can send example via email if necessary. Any ideas why I can’t get the UserTimeline?
Cheers,
Dave
Hi Dave
apologies for the late response. Yes, feel free to send example via email/contact form on this site.
Cheers
Hey Matt,
Fantastic library! Been using the previous version (without oAuth) and now it’s time to update.
After a bit of time here and there got it up and running, however came across two issues: can’t get getFriendsIDs and getFollowersIDs methods to work. Both return following error:
401 Unauthorized – Authentication credentials were missing or incorrect.
the rest of the methods (including getting timeline and posting message) are working fine.
Any ideas?
cheers,
Simon
Hey Simon!
Thanks for the comment. I have replied to this (through your second comment) on the monkehTweet update page.
You can jump directly to this response here: http://www.mattgifford.co.uk/monkehtweets-coldfusion-twitter-cfc-update/comment-page-2/#comment-29965
Many thanks,
Matt
Trackbacks for this post