Instantiating the CFC

Invoking the twitpic object is incredibly simple.
The component has two required parameters; the account name and password for the Twitter user account.

The object also accepts an optional third parameter, 'parseResults'. This is set to false by default, and as such the XML response returned from the API will be in literal String format.
Setting this param to 'true', the XML will be returned through ColdFusion's built-in XmlParse() function, returning a structural representation of the XML.

In my (some may say crude) HTML form, we are creating a very simple user-interface. We are allowing the user to browse for a file, and supply an optional message to send through to the TwitPic API. If the message was present, it would be posted using the Twitter user's details onto the feed with a link to the uploaded image prepended.

In the above example. the form handler event itself is relatively easy. Detecting the submission of the form, the file is uploaded to the temporary directory on the ColdFusion server using the cffile tag.

To send the details to TwitPic, we next run the uploadPic() method within the twitpic.cfc, which accepts the location of the file and the message field from the form.

The uploadPic() Method

The uploadPic() method itself submits an HTTP POST request to the TwitPic API, sending through the file and the message field (if filled in).

API Response

Following a successful post, the API will return an XML response. For any posts that included only photo uploads (no comments or messages), the standard XML output is similar to below, returning the specific ID of the media and the direct link to the file on the twitpic site.

Supplying a message to accompany the uploaded file, the returned output would be similar to the screen grab below:

Here, you can see the response has included the Twitter ID of the user making the post, and the ID of the status created and published in the Twitter feed.

The freshly uploaded image and accompanying message / status update can now be viewed on TwitPic using the URL returned from the response.

Error Handling

The TwitPic API is incredibly simple, especially in comparison to other APIs, including the Twitter API. No complex REST-ful coding here. The output is available in XML only.

To some extent, that may be limiting. As a developer, ideally you would like an API to return method responses in as many varying formats as possible to help with code integration and development.

In this instance, however, it makes it incredbily easy to manage any errors from the API call.

The API itself only specifies four error messages, or instances for error based upon API process, namely

1001 - Invalid twitter username or password

1002 - Image not found

1003 - Invalid image type

1004 - Image larger than 4MB

The detection of error messages was made incredibly easy due to the fact that the XML response would contain a specific node called 'err', as shown in the below sample:

<?xml version="1.0" encoding="UTF-8"?>

To check for the existence of this node, and therefore any error messages returned from the API, an XmlSearch is performed on the returned XML structure, performing a search on the 'err' node name:

<cfset arrXMLError = xmlSearch(cfhttp.fileContent, 'rsp/err') />

Any detection of the 'err' node will populate a pre-defined var-scoped array variable. From this, we can then run the checks on the length of the array, and return the structure within the attributes of the XML to the user, should an error exist.