Information for developers

urlBorg is a project in beta. Things may probably change or break.
You should not rely on it for production-level services or sites! Not yet.

This may not be proper documentation, but if you are a developer or site owner you will probably find valuable information regarding some interesting features of urlB.org.

Follow the urlBorg developers blog for news and thoughts, or visit the urlborg-devel group.

creating shortcuts
redirects
cached pages
APIs
urlBorg developers blog

shortcut creation

The idea is simple, you enter a long URL and you get a short one that redirects to the target URL.

If you are interested in urlB.org, there are some things you should keep in mind:

urlB.org shortcuts are NOT case sensitive!
the total length of the generated shortcut is currently len(http://urlb.org/)+4 but may be longer in the future.
Keep in mind however that 5 character IDs, will be enough to store more than 60.000.000 URLs, so don't expect to see longer ones in the near futrure :-)
A target URL is only stored once. This means that if you or someone else tryes to generate a shortcut for the same target, they will get the same shortcut. (this may change)

redirects

Redirects are done using "HTTP/1.1 301 Moved Permanently” header. This means that your site gets each link's google juice instead of urlB.org (and we think it's the right thing to do).

cached pages

Whenever a URL is added in the urlB.org DB, our bot tries to create a local cache of the page. This will be useful if the target URL disappers, or is temporarily not functioning.

Caching is done in two stages. First a HEAD request is sent to determine if the target URL is an HTML or TEXT page. Only HTML or plain text URLs are cached. If everything goes fine, an HTTP GET request is sent to retrieve the full page
Both HTTP requests wil show up at your logs to come from the urlBorg user-agent. The user-agent string is formated like this:
```
urlBorg/1.0 (+http://www.urlb.org/) [XXXXX]
```
where XXXX is the shortcut ID.
The contents of the cached HTML are not altered in any way. The only alteration done is to insert a <base> tag just before the </head> tag, to make sure any included elements, like stylesheets, images, etc work and relative links point to the right direction.
Caching is done the first time someone creates a shortcut for a given target URL. (this may change)

Checking your web logs for requests from the urlB.org bot, will let you know when one of the pages of your site is referenced by urlB.org and the exact shortcut!

We think that site owners should be aware of links created by urlB.org and this is only the first step in this direction. Expect to see more.

APIs

web interface

If you want a simple way for your web app (or browser applet) to create shortcuts using urlB.org, you may try, linking to

http://www.urlb.org/?url=...

that will pre-fill the target URL in the form.

API Key

We are working on the APIs that will allow developers to make use of urlB.org from their apps.

In order to use most APIs you will have to get your developer key.

PHP

If you are interested to use urlB.org from PHP, read this post.

HTTP-XML

The following types of requests are supported:

create: will create a new shortcut, given a URL.
info: given the shortcut "key", it will return information about it (target URL, total clicks)

http://api.urlborg.com/xml/?action=create&apikey=[your API key]&url=[Target URL, url-encoded]

<?xml version="1.0" encoding="UTF-8"?>
<urlborg>
	<urls>
		<url id="lfnc">
		<original>http://vrypan.net/<original>
		<short>http://urlb.org/lfnc<short>
		<mimetype>image/jpeg</mimetype>
		<length>4746</length>
		<url>
	<urls>
	<error/>
<urlborg>

http://api.urlborg.com/xml/?action=info&apikey=[your API key]&urlkey=[shortcut key]

<xml version="1.0" encoding="UTF-8"?><urlborg>
	<urls>
		<url id="lfpt">
		<original>http://www.pestaola.gr/2007/12/17/mindblog-shuts-down/<original>
		<short>http://urlb.org/lfpt<short>
		<clicks>5<clicks>
		<mimetype>text/html; charset=iso-8859-7</mimetype>
		<length>95000</length>
		<url>
	<urls>

	<error/>
	<urlborg>

The endpoint (http://api.urlborg.com/xml/) will accept both HTTP GET and POST requests. Prefer POST, as GET may be depreciated in the future.

2008-02-15. Please note that the endpoint URL has changed and it is not www.urlb.org/api/ any more!

HTTP-Text

Some applications only need a simple way to transform a given URL to a short URL and are developed in an environment where ther is no XML parsing support, etc. For this kind of applications there is a simple "text" API that will only return the short URL:

http://api.urlborg.com/txt/create.php?apikey=[your API key]&url=[Target URL, url-encoded]