Application Programming Interface

hpics.li 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.hpics.li/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.hpics.li/simple/encode?url=http://lacot.org/ HTTP code 200 + the associated short URL
http://api.hpics.li/simple/encode?url=http://lacot.org/&alias=xavier HTTP code 200 + the associated short URL, eventually with the alias: http://hpics.li/xavier

Decode a short URL

This method is very well suited for decoding short URLs from other web applications. Just call the http://api.hpics.li/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://hpics.li/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.hpics.li/sf_short_url

Additional query-string parameters

Name Description Domain Example
shorturl Keyword of the short url varchar, 1+ characters http://api.hpics.li/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.hpics.li/sf_short_url?longurl=http%3A%2F%2Flacot.org
viewcount Number of times the short url has been visited. positive integers http://api.hpics.li/sf_short_url?viewcount=3
last_visited_at Date / time of the last visit. Datetime, format "YYYY-MM-DD HH:mm:ss" http://api.hpics.li/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 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>
    <Viewcount>23</Viewcount>
    <LastVisitedAt>2010-01-04 09:43:30</LastVisitedAt>
  </SfShortUrl>
</SfShortUrls>

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

[
  {
    shorturl: "lacot",
    longurl: "http://lacot.org",
    viewcount: "23",
    last_visited_at: "2010-01-04 09:43:30"
  }
]

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.

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 in the XML Response, and it will be "null" in the associated JSON feed.

Creating a short url

Request

Method
POST
URI
http://api.hpics.li/sf_short_url
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.hpics.li/sf_short_url.json. In this case, the POST parameter "content" must contain a JSON serialization: 
{
  shorturl: "lacot",
  longurl: "http://lacot.org"
}
or 
{
  longurl: "http://lacot.org"
}

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"
  }
]
HostingPics