DecentURL

Making ugly URLs decent

Bookmarklets

A bookmarklet is a special link you drag to your bookmarks toolbar or add to Favorites/Links, and then whenever you click the bookmarklet it’ll run DecentURL on the address of the current page. Here are two DecentURL bookmarklets:

Let-you-choose bookmarklet (recommended): Requires two clicks, but lets you make sure you’re happy with the title before it creates the decent URL. To use it, just drag this link to your toolbar: DecentURL.

Auto-submit bookmarklet: This one was inspired by Ricardo Cabral’s one, and it tells DecentURL to create the URL immediately. It’s a one-click process, but you don’t get to change the title if you don’t like it. Again, to use it, just drag this link to your toolbar: DecentURL!

And here are versions that open in a new tab, by Joerg Schumann (great for Firefox, but IE7 considers the “new tab” a popup, and blocks it):

Let-you-choose, open new tab: DecentURL.
Auto-submit, open new tab: DecentURL!

API

Note: You now need an API key for the api-get call. Just donate a small amount if you’d like a username (and API key), and your API key will be shown at the bottom of your “my urls” page.

DecentURL has a simple programming interface that returns results as JSON data, so it’s great for use in JavaScript, Python, etc. There are commands to get a decent URL or resolve one, and I’ve also exposed the commands used internally by DecentURL to get a web page’s <title> and a URL’s domain.

You could dig into some code straight away and grab decenturl.py, a DecentURL module for Python, or go to Matthew D’s PHP version.

Or just click an example below to see how it works. The full URL for API calls is http://decenturl.com/api-... but I’ve left off the domain for brevity.

`api-get`: Get or create a decent URL

Call api-get?u=URL&t=TITLE&k=APIKEY and get [status, decent, canonical_url, full_decent].

api-get?u=youtube.com/watch?=pQHX-SjgQvQ&t=medieval&k=APIKEY – but remember to URL-encode the query parameters
api-get?u=youtube.com/watch?=pQHX-SjgQvQ&k=APIKEY – let DecentURL find a title
api-get?u=youtube.z&k=APIKEY – bad URL

`api-resolve`: Convert a decent URL back to the ugly original

Call api-resolve?d=DECENT and get [status, url, utc_date_created].

api-resolve?d=youtube/medieval
api-resolve?d=http://youtube.decenturl.com/medieval – same as above
api-resolve?d=baddy – this decent URL won’t be found

`api-title`: Get a page’s <title>

Call api-title?u=URL&l=MAXLEN and get [status, title, decent_title].

api-title?u=micropledge.com
api-title?u=micropledge.com&l=15 – max 15 chars, but break it nicely
api-title?u=images.google.co.jp – prove that Unicode works

`api-domain`: Get a URL’s base domain

Call api-domain?u=URL&l=MAXLEN and get [status, base_domain].

api-domain?u=www.brush.co.nz
api-domain?u=modwsgi-sites.jottit.com&l=15 – max 15 chars, broken nicely

Query parameters

Use something like JavaScript’s encodeURIComponent() or Python’s urllib.quote() on the query parameters, which are as follows:

u for an ugly URL like http://youtube.com/watch?v=pQHX-SjgQvQ
d for an already-decent one like youtube/medieval-help-desk or http://youtube.decenturl.com/medieval-help-desk
t for a decent title, like Help Desk or help-desk
l for a length (maximum), like 42
k for your API key when using api-get, for example 1234abcd1234abcd1234abcd1234abcd1234abcd

Status codes

Note that on errors (non-ok codes) the API doesn’t return the rest of the results – they’d be invalid anyway.

ok means, well, okay
badurl means you gave a bad URL
badkey means you gave a bad API key
notitle means the page had no <title>
notfound means the decent URL you gave ain’t in the database

To report bugs or suggest improvements, please contact me.

DecentURL

Bookmarklets

API

api-get: Get or create a decent URL

api-resolve: Convert a decent URL back to the ugly original