API Documentation

NOTE: To use jQuery for remote API calls, you may need to create some kind of work-around as most browsers block remote calls per default.

There are currently only two availible API calls: create-link and get-stats. They are called by accessing http://api.drng.dk/create-link.php and http://api.drng.dk/get-stats.php, respectively.

Any drng.dk API call takes its arguments in GET and returns a JSON object, that can easily be interpreted with jQuery, cURL or the likes. The first (and only constant) element of the object is the "success" boolean. This indicates whether your request was succesful or not.

If it was not successful (success == false), there will be an error-element as well, detailing what went wrong. Hence, you should always check for the success of a call as a first thing.

With cURL (PHP) an erroneous call would be like the following (although it's not far off):

<?php
$query = "?url=google.com";
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'http://api.drng.dk/create-link.php'.$query);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, '3');

$content = trim(curl_exec($ch));
curl_close($ch);

$arr = json_decode($content,true);
if(!$arr['success'])
    echo 'Failure! '.$arr['error'];
?>

The problem with the above (which should always print the error), is that it makes a create-link API call with an invalid URL: URLs must always be prefixed with either http://, https://, ftp:// or www.

An example of a faulty call with jQuery could be:

<script type="text/javascript">
$.getJSON("http://api.drng.dk/get-stats.php", {url: "http://drng.dk/qz"}, function(data) {
    if(!data.success) alert(data.error);
    else alert("#WINNING");
});
</script>

This would result in a popup-box with an error-message telling you "Invalid link id given". Why? Because get-stats.php does not take an URL, it takes only the id.

create-link

The create-link call takes one argument: url. The call is really quite straight-forward.

It returns an object containing a link (full short link) and an id (id of link, the last part of short link, used to find stats etc.). The id is the most important part to save, the link is merely there for convenience. The full object could look something like this:

{
    "success": true,
    "id": "4g",
    "link": "http:\/\/drng.dk\/4g"
}

A correct call with jQuery could look something like this:

<script type="text/javascript">
$.getJSON("http://api.drng.dk/create-link.php", {url: "http://deranged.dk"}, function(data) {
    if(data.success)
        alert("Your link has been succesfully created!\n"+
            "Your short link is: "+data.link);
    else
        alert("Oops! Something went wrong with the link creation!\n"+
            data.error);
});
</script>

This prints a message and the short link generated if it was succesful. Otherwise, it will print an error message, passed on directly from the API.

get-stats

The get-stats call takes one argument: id. This is the id provided when creating a link (see above).

It returns an object containing quite some information - all the information that is relevant about the link, actually.

An example object could look like the following:

{
    "success": true,
    "link": "http:\/\/drng.dk\/4g",
    "created_at": 1330211075,
    "original_url": "http:\/\/google.com",
    "visits_day": 3,
    "visits_week": 3,
    "visits_month": 3,
    "visits_year": 3,
    "visits": [
        ["2012-02-26",3]
    ]
    "browsers": [
        ["Firefox",3]
    ]
    "os": [
        ["Windows",3]
    ]
}

Following is each part of the object explained:

Using this knowledge, an easy, naive implementation of some statistics with jQuery can be obtained as in the following example:

<script type="text/javascript">
$.getJSON("http://api.drng.dk/get-stats.php", {id: 1}, function(data) {
    if(data.success) {
        var c = new Date();
        c.setTime(data.created_at * 1000);   //javascript uses ms timestamps
        var date = c.getDate()+'-'+(c.getMonth() + 1)+'-'+c.getYear();

        var html =
            'Original link: <a href="'+data.original_url+'">'+data.original_url+'</a>'+
            '<br/>Visits in the last 24 hours: '+data.visits_day+
            '<br/>Visits since creation ('+date+'): '+data.visits_total;

        $("body").append(html);
    }
});
</script>

The above example would print out a little information about the requested link, such as where it links to, how many visits there have been in the last 24 hours, how many visits there have been in total and exactly when the link was created.

A different naive implementation, this time using cURL, is shown below:

<?php

$downloads = array();

for($id in $download_link_ids) {
    $query = "?id=".$id;

    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, 'http://api.drng.dk/get-stats.php'.$query);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_TIMEOUT, '3');

    $content = trim(curl_exec($ch));
    curl_close($ch);

    $arr = json_decode($content,true);

    if($arr['success']) {
        $downloads[] = $arr['visits_total'];
    }
    else
        echo 'Failure! '.$arr['error'];
}
?>

This gets data for a simple download site, where the amount of downloads of the different links are shown (here, stored in $downloads[]).

With these basic principles of using the API, it should be possible to easily integrate drng.dk with your website.