Using shortner 2 based sites in your application or site

Shortner has been around for a while but always been a pet project of me. With me doing the coding ,hosting and maintenance on it I get little time to actually write about shortner :)  Since the release of shortner 2 I’ve been gathering new ideas for features and optimisations for the codebase. But that time is over :) time to write something about shortner and get the api out there for people to use.

Who is shortner useful for?

Shortner is probaly best used for social sites with limited space *cough*twitter*cough* and podcasters who don’t fancy reading up every link from front to back or referring to their shownotes all the time.

So who is this article for?

For web- and application developers who want to use shortner in their application or webservice.  For this example I’ll use PHP. However you can also put something together with adobe air or VB… Whatever floats your boat. Just follow these steps and create your very first shortner link via your own application!

First step : Obtaining an apikey

You can obtain an api key by requesting one through the website’s interface when logged in. This will also show you your current apikeys and the stats for those. The current process of approving api key requests is manual. However in the future you will be able to obtain a testing api key to use on the test interface.

Second step: Studying the shortner API

Using the shortner api is pretty straight forward. Each method is clearly defined in the Method list and the usage is described in the “api description” . But if you’re anything like me you’d rather just get started and whip together something fast. However you might wanna read the shortner api wiki and this article just in case.Currently shortner 2 suports 2 formats, XML and JSON. Refer to your language of choice for options of reading this data.

Third step: Setting up a connection

To use the shortner api you have to first set up your connection. I advise you to make a method in your class that handles all calls to shortner sites. Make it something you can reuse over and over. If you are planning on writing it in PHP concider using CURL. This takes away all the nitty grittyness of writing your own http client ;)  This is also the place to put your url patterns and include your apikey in them.

Fourth step: Signing in

Most shortner api methods require a sessionid to be used. These sessions require you to first sign in using a username and password. For this you should use the ”
“signIn” method. You need to send the username plain text and the password with an MD5 hash. From this method you will recieve a sessionid, You can store this for later use, the sessions are seperate per api-key, so you can have a user logged in on shortner using 2 different api keys.  The signin process is really important.

Fifth step: Add a URL

Using the “addUrl” method you can add the actual url. This method requires the sessionid parameter to be set.. Either as a get or a post. That is up to you.The basic parameters for this method are : sessionid, url , the rest of them are optional. But please check out the method list as there are several interesting. By default all urls are recycled. So if someone else already added that url, that one will be returned. However if that one is password protected it will be re-added.

Last step : Sign out
Sign the user out using the “signOut” method.Although this is not required, users will be able to see what tools they are logged in with in the future.  So cleaning up after yourself is a very nice thing to do.

Please note: Statistics & blocking

Shortner keeps track of the usage of the api. So if you cause too many authentication errors you will automatically be blocked. You can check out your api key stats in your panel.

Example class:

Look over this sample class which you can use to model your own class after.

Shortner2 in the future

Soon more api methods will be available to read statistics for your api and the urls of your users. Also the retrieval of all urls that have been created using your apikey across all shortner 2 sites. As well as a testing version of shortner2 which include new methods and method changes.

Wrote your own library?

Drop me a comment with the url!

Shortner sites:

These are some public shortner2 enabled sites. There are more but those are more meant for a specific goal.

http://www.shortner.com/
http://www.qrk.me/

A dutch shortner:

http://www.vetkort.nl

Some sources
Shortner wiki
A sample class with usage code at the bottom

Want to contact me ?
Try twitter: @webdevvie
Oh yeah, this article was crossposted to twitter and the url was shortnered using the shortner api :)

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.