1. urlBorg API overview. version 2.1
-------------------------------------
The following urls are under http://urlborg.com/api/ 

/api/<api_key>
	/url
		/create/<original_url> -- DONE [8]
		/info/<short_id> -- DONE 
		/stats/<short_id> -- DONE [3]
		/synonyms/<short_id> -- TBA
		/list/<results_page> -- DONE [5]
		/export/<short_domain>/<results_page> -- DONE [7]

	/domain
		/status/<long_domain> -- DONE 
		/ping/<long_domain> -- DONE 
		/list/<results_page> -- DONE [4]
	/key
		/validate

	/create/<long_url> [6]


2. Generic info.
----------------

- "api_key": all requests to the API must be done using a valid API key. To get your key, visist http://www.urlborg.com/account/

- "original_url" is also refered as "long URL". This is the original URL you will want to shorten.

- "short URL" is the URL returned by urlBorg. This is *usually* in the form http://ub0.cc/<x>/<y>
where:
	- <x>,<y> is a case sensitive string (digits 0..9 and letters b..z, B..Z (no vowels to minimize the possibility of swera words)
	- the part after the short domain, i.e. <x>/<y> is the "short id".
	- the domain ub0.cc is the default domain used for short URLs. However, other domains may be used too.
	- Users and third party services making use of urlBorg MUST USE THE SHORT URLS WITHOUT ALTERING THEM.

- HTTP request method:
All requests are HTTP-GET, unless specified differently.
Current exception is only url/create that supports both GET and POST. If you use POST you can specify the extra variable "force_preview" that will create a short URL with forced preview.


3. Output format
----------------
All /url/ and /domain/ actions (ex. "create", "info", "ping", etc.) can be suffixed with .xml or .json to return responses in the corresponding format.
If no format is specified, XML is prefered.

Examples: 
- /api/api_key/url/create.xml/http://vrypan.net
- /api/api_key/url/create.json/http://vrypan.net
- /api/api_key/domain/list/1
- /api/domain/list.json/1

4. Notes.
---------
[3] /url/stats/<short_id>
Currently, the provided stats are click for current day, month and year.

[4] /api/domain/list/<page>
Up to 100 domains are displayed per page. So, page 1 is 0-99, page 2 for 100,199, etc. 
Domains are sorted by creation date, first is oldest.
Sorting by older to newer, means that applications could jump to page n+1 if they have already requested page n, even if new data have been added.

[5] /url/list/<page>
same as [4] but for the URLs added.

[6] /create/<long_url>
This is a "plain text", simple API. It will return short URL. No formating, no markup. Content type = text/plain

[7] Same as [5] but only for the short URLs using the specified <short_domain>.

--
Last updated: 2008-07-18 by Panayotis Vryonis <panayotis@urlb.org>