whit.me
multiple URL shortening
API services documentation
whit.me provides a set of API services for the integration of URL shortening in your browser, in external Websites, and into any application. Currently, these API services are bookmarklets, HTML embedding, and JSON Web services.
Table of Contents
Browser bookmarklets
The simplest way of using whit.me outside the Website itself is by using our bookmarklets (i.e., bookmarks with "smart functiontality"). To begin using them, you just need to bookmark them in your browser - preferably by dragging them to you bookmarks bar. Head up to Wikipedia for more info about bookmarklets. We currently support the following bookmarklets:
- whit.me bookmarklet, to create a short URL based on the Web page that is currently being displayed;
- whit.me bookmarklet++, which captures selected text on the Web page and uses it as the annotation for the short URL created. if no text is selected, the page's title is used instead;
- twit on a whit, builds upon the whit.me bookmarklet++ and directly posts a new message on twitter. note: this bookmarklet requires that you have an account on twitter and properly logged in on twitter's Website. whit.me will redirect you to your twitter home with the status text properly set up (you'll just need to hit the update button).
HTML embedding
If you use whit.me services in HTML Webpages, you can benefit of automatic URL expansion to present users with the corresponding set of hyperlinks. This can be done just by adding the following snippet of HTML to the <head> element of your Webpage:
<script src="http://www.whit.me/scripts/whitme-connector.js" type="text/javascript"></script>
Below you can see an example of the resulting script integration:
A working example is also available.
JSON Web services
We provide a simple HTTP-based API that allows developers to interact with whit.me's URL shortening service. All API requests must be based on the following URL pattern:
http://www.whit.me/api/operation?parameters
All operations support the Accept: application/json HTTP header to ensure that all responses are encapsulated into JSON objects.
This API also supports the JSONP pattern, by appending a callback=? parameter form to whit.me's API URLs, for seamless integration with cross-domain Javascript client-side technologies. In this parameter, replace ? with an appropriate Javascript function name.
Currently, we support the following services:
URL shortening
- operation: short
- parameters:
- url: the original URL to be shortened. This parameter can be repeated as many times as desired, as whit.me supports multiple URLs.
- urlnote: a note to be paired with a URL. This parameter must be repeated as many times as url parameters. urlnote parameters must be ordered in sync with corresponding URLs.
- note: the main note to be attached to the shortened URL.
- hash: a custom URL alias (for readable shortened URLs). whit.me will return a generated alias if the supplied parameter already exists or is invalid (e.g., reserved keywords).
- result:
- http://whit.me/alias, the shortened URL form.
- {'url': 'http://whit.me/alias'}, the shortened URL form, if the callback=? parameter form is passed or if the Accept: application/json HTTP header is set.
- {'error': 0, 'description': 'Invalid whit.me alias or incorrect URL.'}, for malformed URLs.
- {'error': 1, 'description': 'Invalid whit.me alias.'}, for malformed aliases.
- example:
by executing the following HTTP request:
GET http://www.whit.me/api/short?url=http://www.areallylongurlgoeshere.com/our service will return an HTTP response whose content is the shortened URL, e.g.:http://whit.me/b9i9HU
URL expansion
- operation: expand
- parameters:
- hash: the whit.me alias to be expanded.
- result:
- {'urls': ['url 1', 'url 2', ...], 'urlnotes': ['url 1 note', 'url 2 note', ...], 'note': 'a note goes here'}, the list of URLs bound to the supplied hash parameter, corresponding URL notes, as well as the main note.
- {'error': 0, 'description': 'Invalid URL.'}, for malformed URLs.
- {'error': 1, 'description': 'No hash provided.'}, if the alias doesn't exist.
- example:
by execuing the following HTTP request:
GET http://www.whit.me/api/expand?hash=XxJ7E8our service will return an HTTP reponse whose content is an array of expanded URLs, e.g.:{'urls': ['http://whit.me', 'http://whit.me/api/docs'],
'urlnotes': ['main page', 'documentation'],
'note': 'Some links about whit.me'}