Introducing the Bitly Cloud Connector for Mule

Over the last few years, the web has seen an explosion in the number of URL shortening services. The majority of this growth is due to popular microblogging and social networking sites such as Twitter. And with this growth, comes the demand for developers to create their own apps to take advantage of these services.

One of the most popular shortening services is Bitly - http://bitly.com/. Since January 2011, Bitly have seen nearly 100 billion human clicks on bitly-powered links. And like any good service, they have an API. Not only does the API provide URL shortening and expanding, they also provide stats for your links and also a range of realtime data APIs that allow you to search for specific keywords and filter by topic, social network, location, domain and language to return related content currently receiving the most attention on the internet.

Bitly are now providing version 3 of their APIs. And anyone working with them will know that they have their fair share of idiosyncrasies, particuarly error codes! So I am pleased to announce the Mule Cloud Connector for the Bitly APIs.

Geting Started with the Bitly Cloud Connector

Authentication

The connector supports two authentication mechanisms: Basic auth(OAuth - Client-Credentials flow) and OAuth(Web Flow). Bitly have deprecated API Key authentication and has not been included as part of this connector.

Basic Auth Example

A simple example to shorten a long URL using Basic Authentication:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:bitly="http://www.mulesoft.org/schema/mule/bitly"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/bitly http://www.mulesoft.org/schema/mule/bitly/1.0-SNAPSHOT/mule-bitly.xsd">
 
<bitly:config name="bitly" username="${bitly.username}" password="${bitly.password}" doc:name="Bitly (Basic Auth)"/>
 
<flow name="shorten" doc:name="shorten">
<bitly:shorten username="${bitly.username}" password="${bitly.username}" longUrl="http://shop.oreilly.com/product/0636920025726.do"
config-ref="bitly" doc:name="Bitly" />
</flow>
 
</mule>

Basic Auth - Multi-tennant

The connector supports Connection Management and allows a user to specify credentials at the operation level to allow multi-tennancy. Here is a simple example to shorten a long URL using Basic Authentication at the operation level:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:bitly="http://www.mulesoft.org/schema/mule/bitly"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/bitly http://www.mulesoft.org/schema/mule/bitly/1.0-SNAPSHOT/mule-bitly.xsd">
 
<bitly:config name="bitly" doc:name="Bitly (Basic Auth)"/>
 
<flow name="shorten" doc:name="shorten">
<bitly:shorten username="${bitly.username}" password="${bitly.username}" longUrl="http://shop.oreilly.com/product/0636920025726.do"
config-ref="bitly" doc:name="Bitly" />
</flow>
 
</mule>

OAuth

A simple example to shorten a long URL using OAuth:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:bitly="http://www.mulesoft.org/schema/mule/bitly"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/bitly http://www.mulesoft.org/schema/mule/bitly/1.0-SNAPSHOT/mule-bitly.xsd">
 
<bitly:config-with-oauth name="bitlyOAuth" apiKey="${bitly.apiKey}" apiSecret="{bitly.apiSecret}" doc:name="Bitly (OAuth)">
<bitly:oauth-callback-config domain="localhost" localPort="8082" remotePort="8082" path="callback" />
</bitly:config-with-oauth>
 
<flow name="shortenWithOAuth" doc:name="shortenWithOAuth">
<http:inbound-endpoint exchange-pattern="request-response"
host="localhost" port="8081" path="authorize" doc:name="HTTP" />
 
<bitly:authorize config-ref="bitlyOAuth" doc:name="Bitly" />
 
<bitly:shorten longUrl="http://shop.oreilly.com/product/0636920025726.do"
config-ref="bitlyOAuth" doc:name="Bitly" />
</flow>
 
</mule>

Data formats

As with all Cloud Connectors, request formats are abstracted away into easy to use attributes and nested elements etc. These can be found in the connector documentation - http://ryandcarter.github.com/bitly-connector/mule/modules.html

Response formats are provided as the raw JSON responses from the Bitly API which can be found in the Bitly API docs - http://dev.bitly.com/api.html. This can be easily manipulated in Mule using the provided JSON transformers and data bindings.

Here's a simple example the creates a URI for an exising image in Amazon S3 using the S3 connector, shortens the URI using the Bitly connector and posts to Twitter using the Twitter connector.

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:twitter="http://www.mulesoft.org/schema/mule/twitter"
xmlns:s3="http://www.mulesoft.org/schema/mule/s3"
xmlns:bitly="http://www.mulesoft.org/schema/mule/bitly"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/twitter http://www.mulesoft.org/schema/mule/twitter/current/mule-twitter.xsd
http://www.mulesoft.org/schema/mule/s3 http://www.mulesoft.org/schema/mule/s3/current/mule-s3.xsd
http://www.mulesoft.org/schema/mule/bitly http://www.mulesoft.org/schema/mule/bitly/1.0-SNAPSHOT/mule-bitly.xsd">
 
<twitter:config name="twitter" consumerKey="${twitter.consumer.key}"
consumerSecret="${twitter.consumer.secret}" accessKey="${twitter.access.key}"
accessSecret="${twitter.access.secret}" />
 
<s3:config name="s3" accessKey="${s3.accessKey}" secretKey="${s3.secretKey}" />
<bitly:config name="bitly" username="${bitly.username}" password="${bitly.password}" doc:name="Bitly (Basic Auth)"/>
 
<flow name="shorten" doc:name="shorten">
<s3:create-object-uri bucketName="my-bucket" key="logo.jpg" config-ref="s3"/>
<bitly:shorten username="${bitly.username}" password="${bitly.username}" longUrl="#[payload]"
config-ref="bitly" doc:name="Bitly" />
<twitter:update-status status="New image: #[payload['data']['url']]"
config-ref="twitter" />
</flow>
 
</mule>

In this example we simply convert the JSON Bitly response to a HashMap using the json-to-objec transformer and use MEL's(Mule Expression Language) streamlined syntax to access the "url" property from the map to post to Twitter.

Give me the code!

The connector can be found on Github at: https://github.com/ryandcarter/bitly-connector. It's only in beta a the moment; so if you have any issues please report them on Github.

Going Further

As you can see mashing up multiple APIs is childs play wih Mule Cloud Connect and there are so many more things you can do with this Cloud Connector; mashup the S3, Twitter and Bitly Cloud Connectors to post shortened images to Twitter from an S3 bucket or maybe mashup the Github and Bitly Cloud Connectors to create shortened sharable gists. If you have any cool examples or enhancements, please just send a pull request.

And of course if you want more info or help with Mule Cloud Connect, I can recommend a very good book: http://oreil.ly/mule-cloud :)