Application Programming Interface

xav.cc offers both a simple "GET query-string" based API, and a more complete and powerful REST-style API, which allows to create and retrieve short URLs.

For busy ones: the simple query-string based API

Encode a short URL

This method is very well suited for short URL creation from other web applications. Just call the http://api.xav.cc/simple/encode service, along with one or two query-string parameters:

url:
The url to shorten
alias:
This optionnal paramater is the alias that the user would like to get as a short url alias, instead of a randomly generated one. Please note that if this alias is already taken, a randomly generated one will be used.

The service might answer in three ways:

Here are some request samples:

Request Result
http://api.xav.cc/simple/encode?url=http://lacot.org/ HTTP code 200 + the associated short URL
http://api.xav.cc/simple/encode?url=http://lacot.org/&alias=xavier HTTP code 200 + the associated short URL, eventually with the alias: http://xav.cc/xavier

Decode a short URL

This method is very well suited for decoding short URLs from other web applications. Just call the http://api.xav.cc/simple/decode service, along with an "alias" parameter, which represents the short URL alias to decode. This alias might either be a simple string (eg. "xavier"), or a complete short URL (eg. http://xav.cc/xavier).

The service might answer in three ways:

Rest-style API for retrieving short urls

This is a more complete and powerful API, which should be used when building rock-solid applications.

Request

Method
GET
URI
http://api.xav.cc/sf_short_url

Additional query-string parameters

Name Description Domain Example
shorturl Keyword of the short url varchar, 1+ characters http://api.xav.cc/sf_short_url?shorturl=lacot
longurl You may pass a long url, which allows to retrieve the short url associated to this long url. valid HTTP URLs http://api.xav.cc/sf_short_url?longurl=http%3A%2F%2Flacot.org
real_longurl You may pass a long url, which allows to retrieve the short urls which redirect to this long url as a real target (so, even if there are several redirections before accessing this target). valid HTTP URLs http://api.xav.cc/sf_short_url?real_longurl=http%3A%2F%2Fen.wikipedia.org%2Fwiki%2FSpam
is_warning Whether or not we consider that there might be a problem with the long url (spam, abusive content, etc.). boolean http://api.xav.cc/sf_short_url?is_warning=false
viewcount Number of times the short url has been visited. positive integers http://api.xav.cc/sf_short_url?viewcount=3
created_at Date / time of the creation of the short url. Datetime, format "YYYY-MM-DD HH:mm:ss" http://api.xav.cc/sf_short_url?created_at=2009-12-29+09%3A17%3A21
last_visited_at Date / time of the last visit. Datetime, format "YYYY-MM-DD HH:mm:ss" http://api.xav.cc/sf_short_url?last_visited_at=2009-12-29+09%3A17%3A21

Response

When valid parameters are passed to the web service, the Response uses the HTTP code 200 (Success), along with a JSON Response body encoded in utf-8. If the client supports it, the Response body is served gzipped. 

[
  {
    shorturl: "lacot",
    longurl: "http://lacot.org",
    real_longurl: null,
    title: "Chez Xavier - Symfony gets a REST generator",
    is_warning: false,
    viewcount: "23",
    last_visited_at: "2010-01-04 09:43:30",
    created_at: "2009-12-27 21:58:58"
  }
]

The default serialization format used is JSON, but you can choose XML as an alternative, by using the URI http://api.xav.cc/sf_short_url.xml instead of the default http://api.xav.cc/sf_short_url: 

<?xml version="1.0" encoding="utf-8"?>
<SfShortUrls>
  <SfShortUrl>
    <Shorturl>lacot</Shorturl>
    <Longurl>http://lacot.org</Longurl>
    <Title>Chez Xavier - Symfony gets a REST generator</Title>
    <IsWarning>0</IsWarning>
    <Viewcount>23</Viewcount>
    <LastVisitedAt>2010-01-04 09:43:30</LastVisitedAt>
    <CreatedAt>2009-12-27 21:58:58</LastVisitedAt>
  </SfShortUrl>
</SfShortUrls>

You may also use YAML as a representation format, using the the URI http://api.xav.cc/sf_short_url.yaml: 

sfShortUrl:
  -
    shorturl: lacot
    longurl: 'http://lacot.org/'
    real_longurl: null
    created_at: '2009-12-27 21:58:58'
    last_visited_at: '2010-11-22 12:45:34'
    title: 'Chez Xavier - Symfony gets a REST generator'
    is_warning: false
    viewcount: '49'

Using the JSON serializer is interesting for mobile clients, as it is less verbose than the XML one, and therefore must be slightly faster to transfer for large collections of data. On the other side, you may want to prefer the XML serializer if you use some automatic tools which do not support JSON.

The items in the response-body are sorted by creation date descending (most recent first), with a maximum of 50 items. When a non-acceptable parameter is passed to the service, a 406 (Not Acceptable) Response code is returned to the client.

If the link has never been visited, the field LastVisitedAt won't be present in the XML Response, and it will be "null" in the associated JSON and YAML feeds.

Creating a short url

Request

Method
POST
URI
http://api.xav.cc/sf_short_url.xml
XML values
A POST parameter named "content" must be sent with the request. It must contain a XML serialization of the short URL to be created: 
<?xml version="1.0" encoding="utf-8"?>
<SfShortUrl>
  <Longurl>http://lacot.org</Longurl>
  <Shorturl>lacot</Shorturl>
</SfShortUrl>
or 
<?xml version="1.0" encoding="utf-8"?>
<SfShortUrl>
  <Longurl>http://lacot.org</Longurl>
</SfShortUrl>
As for short urls retrieval, it is possible to use JSON as a serialization format, by using the URI http://api.xav.cc/sf_short_url. In this case, the POST parameter "content" must contain a JSON serialization: 
{
  shorturl: "lacot",
  longurl: "http://lacot.org"
}
or 
{
  longurl: "http://lacot.org"
}
Of course, you may also POST YAML content to the YAML service, using the URI http://api.xav.cc/sf_short_url.yaml.

XML Parameters

Name Description Domain required
Longurl The long url to be shortened. valid HTTP URLs yes
Shorturl Keyword for the short url. This parameter is optionnal and, if ommited, a short url keyword will be generated instead. varchar, 1+ characters no

Response

When valid parameters are passed to the web service, the Response uses the HTTP code 200 (Success), along with a XML Response body encoded in utf-8. If the client supports it, the Response body is served gzipped. 

<?xml version="1.0" encoding="utf-8"?>
<SfShortUrls>
  <SfShortUrl>
    <Shorturl>lacot</Shorturl>
    <Longurl>http://lacot.org</Longurl>
  </SfShortUrl>
</SfShortUrls>

When a non-acceptable parameter is passed to the service (malformed XML, unknown tags in the XML payload, etc.), a 406 (Not Acceptable) Response code is returned to the client.

If the JSON serialization format is in use, the Response body will contain JSON formatted data: 

[
  {
    shorturl: "lacot",
    longurl: "http://lacot.org"
  }
]