API

AllAroundSiena API enables easy integration for broadcasting to your Telegram Channels using our platform.

Introduction

AllAroundSiena API use REST interface to provide register, publish and verify methods. Just to provide some examples, we choose to use Unirest - Lightweight HTTP Request Client Libraries.

All request should be sent to https://www.allaroundsiena.com/rest with proper headers and body, like:


$headers = array('Accept' => 'application/json');
$data = array('key' => $api_key,
    [...]
);
$body = Unirest\Request\Body::multipart($data);
$result = Unirest\Request::post('https://www.allaroundsiena.com/rest/register', $headers, $body);
		    
You can test API interface using REST client like Insomnia.


Register method

You need to get an unique API key before publishing from your source. To get one, you can use register method like:


$headers = array('Accept' => 'application/json');
$data = array('key' => '',
    'blog_name' => $blog_name,
    'blog_description' => $blog_description,
    'blog_admin_email' => $blog_admin_email,
    'blog_language' => $blog_language,
    'blog_url' => $blog_url,
);
$body = Unirest\Request\Body::multipart($data);

$result = Unirest\Request::post('https://www.allaroundsiena.com/rest/register', $headers, $body);

if($result->code == '200') {
    if(isset($result->body->apikey)) {
	$api_key = $result->body->apikey;
    } else die('Error');
} else die('Error');
		    
Mandatory fields are blog_name,blog_admin_email and blog_url. Please note that e-mail address specified in blog_admin_email will receive a confirmation link to unlock the API key.


Verify method

If you just want to verify if your API key is still valid, you should use verify method:


$headers = array('Accept' => 'application/json');

$data = array('key' => $api_key);

$body = Unirest\Request\Body::multipart($data);

$result = Unirest\Request::post('https://www.allaroundsiena.com/rest/verify', $headers, $body);

if($result->code == '200') {
    echo("Connected !");
} else {
    echo("Error:" . $result->code);
}				
		    
In JSON format, system reply like:

{
    "success": "verified",
    "message": "No errors detected"
}
		    
if API key was verified successfully or:

{
    "error": {
        "code": 403,
        "message": "Wrong Api Key"
    }
}
		    
if not.


Publish method

To publish post to your channel, you need to use publish method:


$headers = array('Accept' => 'application/json');

$data = array('key' => $api_key,
    'title' => $post_title,
    'excerpt' => $post_excerpt,
    'author' => $post_author,
    'date' => $post_date,
    'image_url' => $post_image_url,
    'tags' => $post_tags,
    'url' => $post_url,
);

$headers = array('Accept' => 'application/json');
$body = Unirest\Request\Body::multipart($data);

$result = Unirest\Request::post('https://www.allaroundsiena.com/rest/publish', $headers, $body);

if($result->code == '200') {
    echo("Published !");
} else {
    echo("Error:" . $result->code);
}				
		    
Please note that AllAroundSiena checks for duplicates (using hash checksum). $post_tags need to be comma-separated (like first tag, second tag, ...) and $url is the unique URL for the post, the permalink.


Queue method

To see the publish queue of your channel, you can to use queue method:


$headers = array('Accept' => 'application/json');
$data = array('key' => $api_key);
$body = Unirest\Request\Body::multipart($data);
$result = Unirest\Request::post('https://www.allaroundsiena.com/rest/queue', $headers, $body);
		    
Of course you need to specify the api key of the source you want to check. As return, in JSON format, the last 10 entries in publish queue:

{
    "success": 10,
    "result": [
        {
            "id": "1559",
            "title": "Un divertente esperimento di reti neurali: Quick, Draw!",
            "added": "11:11:20 19-11-2016",
            "published": 
        },
        {
            "id": "1543",
            "title": "Canon EOS M10",
            "added": "07:11:11 18-11-2016",
            "published": "08:11:12 19-11-2016"
        },
        {
            "id": "1542",
            "title": "Monitoraggio del traffico VoIP con Homer ed OpenSIPS",
            "added": "07:11:46 18-11-2016",
            "published": "08:11:12 19-11-2016"
        },
        [...]
    ]
}
		
Empty "published" field means that the post is waiting for publication on Telegram channel. "ID" is the unique id for this post.


wp-allaround Wordpress plugin

Code was taken from wp-allaround Wordpress plugin, available on GitHub and on Wordpress Plugin Repository.