Using Ph.ly with the Shortly Safari extension

Ever since hearing about Philly's own URL shortener, I decided I wanted to replace bit.ly as my default shortening service in the Shortly Safari extension. Luckily Shortly v2 and higher supports custom endpoints for just this sort of thing.

The key is to get some information directly from Ph.ly's owners, Technically Philly. They're an awesome bunch and I was happy to hear back from their staff so quickly about my request for information. What they'll need to provide you is something called a secret signature token. It's an alternative method from using the classic username/password combinations of the past. Once you have this information, putting the custom endpoint in is a breeze. Here's the steps I followed to get it to work:

  1. Email info@technicallymedia.com with a subject similar to Custom endpoint for ph.ly API and let them know what you're trying to do.
  2. They'll write back with your secret signature token.
  3. Use this token in the following string: http://ph.ly/yourls-api.php?signature=yoursecretsignaturetoken&action=shorturl&url=%@&format=json.
  4. Save this string into the Extension preference pane as indicated in the screen cap below.
  5. Success!
Screen Shot 2012 10 19 at 11 14 24 AM

That's pretty much all there is to it. Since I'm new to working with APIs and such, I had some difficulty when I was playing around with the required parameters for Shortly. Between a very brief thread on Github and the information found on ph.ly's API page (the service uses YOURLS), I was able to hack this out in about 15 minutes. The trick is to have the endpoint contain the following parameters which aren't initially obvious:

  • action = shorturl
  • url=%@
  • format = json

The action parameter specifies the command you're wanting the endpoint to execute. Other options you can choose here are expand(for reverse translation of a shortened URL), url-stats (for checking statistics on your shortened URLs), and stats (for statistics on recent shortened URLs by other users).

The parameter url=%@ took me the longest to find, simply because it's not in the YOURLS documentation. Rather, I had to find this string using some information on the Shortly's Github page. I found that the %@ attribute is a requirement for Shortly to pull the URL in your address bar into the request from YOURLS. None of the documentation on the YOURLS page gave me that information.

The last bit of information - format=json - is what I believe to be the best format to use, since that's the format Shortly is expecting to be returned, based on the Github page. Although I have had success with xml option, I use json simply because that's what the Shortly documentation specifies. (Why risk breaking things?). It should be noted that I did not have success with simple attribute and it caused Shortly to enter an infinite loop.

In the end, hacking this extension to work with Ph.ly (or any YOURLS custom short domain) was a matter of finding a common ground to which both the extension and service could talk to one another. Seeing that Shortly is compatible with Ph.ly makes the extension more valuable to me and gives me an added benefit of using a custom short URL domain when I share links.

If you also have some time and you enjoy being civic-minded, check out Ph.ly News Weekly. It's a Friday-morning email compiled from articles pulled from newspapers, TV stations, blogs, social and independent media throughout the metropolitan area and culled down to the three most interesting stories to impact our region. You can check out their archive here as well as sign up.

Kudos to Brian James Kirk from Technically Media for supplying the needed information to make this whole thing work.