REST API (beta) Documentation
Shr.tn's data and functionalities are accessible to developers through a simple REST Application Programming Interface (API). This is a reference guide to shr.tn REST API v1 (beta).
Basics
Okay, let's make things easy and fast and go straight to the point.
shr.tn's endpoint is the following : http://shr.tn/api/v1/
All the requests you make to the API server are HTTP GET requests.
Authentication
In every request, you will have to authenticate yourself. To do so, you must supply your authentication credentials in the query string arguments you pass in the request url:http://shr.tn/api/v1/SERVICE_NAME?ARGUMENTS...&username=YOUR_USERNAME&api_key=YOUR_API_KEY
VERY IMPORTANT: NEVER SUPPLY YOU PASSWORD IN THE REQUEST URL. USE YOUR API KEY INSTEAD.
In order to obtain an API key, you need to create a free account, then request an API key in your account page.
You can reset your API key at any time ; doing so will disable all your previous API keys, leaving functional the last generated key.
Therefore, keep in mind that you will need to update your code by removing any old API key and replacing it with the new one. Don't forget this ;).
Formats
The next thing to know is that shr.tn's API offers 3 types of response formats :
For jsonp, simply use the json format and append &callback=callback_function_name to your url.
Here is an example of a json response, returned as a result of a url-shortening request (more on this in the last section):
{"data" {"hash":"173ffc0f2325fdedf66030371b320ee4f8b72e2f","short_url":"http://shr.tn/s8Tp","long_url":"http://www.website.com"},...}
This is the same example in xml format:
<?xml version="1.0" encoding="utf-8"?><response><data><hash>173ffc0f2325fdedf66030371b320ee4f8b72e2f</hash><short_url>http://shr.tn/s8Tp</short_url><long_url>http://www.website.com</long_url></data>...
A response in text format will output the raw short url:
http://shr.tn/s8Tp
Response
The response contains data returned in the format specified by the format argument in the HTTP request url.
Before we expose the available services, remember that, whatever the requested service is, every response has two parts: data and resp.
{"data" {},..."resp" {...},}
data is the part that contains the result of the request. Its content depends on the service you requested, so you'll find more details about it in each service description.
resp contains information about the response status. It is the part that indicates whether the request was successfully processed, or that an error has been encountered. Its content is the same for every request and only the returned values will vary.
Structure of the resp object
- status: indicates if the request was successfully processed or failed:
- 1: success
- 0: failure
- code: the HTTP code returned after the request was processed (check the table below for possible values)
- message: the text relative to the returned HTTP code (check the table below for possible values)
| code | message | meaning |
|---|---|---|
| 200 | OK | The request was successfully processed and the long url or short url or number of clicks were found and returned. |
| 201 | Created | A url-shortening request has been successfully processed and a short url was created |
| 400 | Bad Request | Indicates the arguments that were supplied are invalid |
| 403 | Forbidden | Authentication failure meaning the supplied credentials were invalid. |
| 404 | Not Found | A non-existant long or short url were requested to be processed |
| 500 | Internal Server Error | General error occured on the server |
| 501 | Not Implemented | An unknown service name was requested. |
API
Okay, here we are.
In this beta version, shr.tn's API offers 3 major services:
- short: shortens a long url and returns the result
- long: returns the long version of a short url
- clicks: returns the number of clicks of a short url
/api/v1/short
http://shr.tn/api/v1/short?long=LONG_URL&format= RESPONSE_FORMAT&username=YOUR_USERNAME&api_key=YOUR_API_KEY
As you may have guessed, this service shortens a long url using the supplied authentication credentials and returns the result in the specified format.
A json formatted response may look like this example:
{"data" {"hash":"173ffc0f2325fdedf66030371b320ee4f8b72e2f","short_url":"http://shr.tn/s8Tp","long_url":"http://www.website.com"},resp {"status":"1""code":"201""message":"Created"}}
data structure:
- hash: hash of the long url
- short_url: the resulting short url
- long_url: the original long url
Supported response formats: json/jsonp, xml and text
Note that in text mode, only the short url will be returned. This format can be used with a desktop or web client that let you configure your own url shortener (take a look at the last section)
/api/v1/long
http://shr.tn/api/v1/long?short=SHORT_URL&format= RESPONSE_FORMAT&username=YOUR_USERNAME&api_key=YOUR_API_KEY
This does exactly the opposite of the short service, it takes a short url then using the supplied authentication credentials it looks for its corresponding long url, and returns the result in the specified format.
A json formatted response may look like this example:
{"data" {"hash":"173ffc0f2325fdedf66030371b320ee4f8b72e2f","short_url":"http://shr.tn/s8Tp","long_url":"http://www.website.com"},resp {"status":"1""code":"200""message":"OK"}}
data structure:
- hash: hash of the long url
- short_url: the short url
- long_url: the original long url
Supported response formats: json/jsonp, xml and text
Note that in text mode, only the long url will be returned.
/api/v1/clicks
http://shr.tn/api/v1/clicks?short=SHORT_URL&format= RESPONSE_FORMAT&username=YOUR_USERNAME&api_key=YOUR_API_KEY
This service takes a short url then using the supplied authentication credentials, it calculates the number of clicks, and returns the result in the specified format.
A json formatted response may look like this example:
{"data" {"hash":"173ffc0f2325fdedf66030371b320ee4f8b72e2f""clicks":"1268""global_clicks":"4928"},resp {"status":"1""code":"200""message":"OK"}}
data structure:
- hash: hash of the long url
- clicks: number of clicks specific to the supplied short url
- global_clicks: global number of clicks of the original long url (ie. sum of all the specific short urls clicks)
Supported response formats: json/jsonp, xml and text.
Note that in text mode, only the number of clicks specific to the short url will be returned.
Integration with your favourite client
If you'd like to configure your favourite application or website to use shr.tn for shortening urls you share, then you will simply have to use the following endpoint :
http://shr.tn/api/v1/short?long=LONG_URL&format=text&username=YOUR_USERNAME&api_key=YOUR_API_KEY
Please note that you will have to use a text format for the returned data type and that you may need to replace LONG_URL with a special code used by your application (as an example, TweetDeck uses %@)
