Introduction

REST API is designed to connect and work with Cutso system. All available commands are described below. Requests need to be sent with POST or GET method to url address https://iiv.pl/api/command_name.

Every request, except login, register need to include ACCESS_TOKEN in headers:
Authorization: Bearer ACCESS_TOKEN . ACCESS_TOKEN you replace with string received as a response to login (command auth/login).

Via API you can:

Log in to system using email and password
Log out
Retrieve shortcut links list
Create shortcuts
Retrieve details about shortcut link
Access account details
Change account password
Register new accounts
Retrieve session details

PHP

                       
// POST request and an example
$token = 'ACCESS_TOKEN';
$headers = array();
$headers[] = 'Authorization: Bearer '.$token;
$ch = curl_init();
$postfields = array(
    'example_field'=>'value'
);
curl_setopt($ch, CURLOPT_URL, 'https://iiv.pl/api/command_name);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($ch);

Log in

One can log in using the e-mail address and password. The required fields are email and password. The request is send using POST method to the addresss auth/login. As a reply one gets json with the basic data and ACCESS_TOKEN required to use other operations.

ACCESS_TOKEN is valid 60 minutes after logging in and it is assigned to IP address from which the logging occured. There is no possibility to use ACCESS_TOKEN for a different IP adressses and after 60 minutes from logging in.

To get the remaining session time one has to use the session method - the opis of this method can be found here.

Attention! There is only one session per user. It is not possible to log in on more than one defice at the same moment.

If you use commad login again, it generates new ACCESS_TOKEN

Parameters

Parameter	Type	Required	Description
email	string	Yes	E-mail address
password	string	Yes	Password

Reply

It returns json with data session including ACCESS_TOKEN that is used for authorization and it should be set in the "Authorization" header::

Authorization: Bearer ACCESS_TOKEN

Errors

Reply	Description
Empty credentials	One parameter is missing
Wrong credentials	Incorrect login parameters

PHP

                       
function login(){
	$postfields = array('email'=>'[email protected]', 'password'=>'yoursecretpassword');
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, 'https://iiv.pl/api/auth/login');
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
	curl_setopt($ch, CURLOPT_POST, 1);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
	$result = curl_exec($ch);
	return $result;
}

print_r(login());
// returns
{
  "status": "OK",
  "data": {
    "session": {
      "token": "JBsuKDFUlfroPJAKPdOwviBhPKN5e42i", // ACCESS_TOKEN
      "ip": "127.0.0.1",
      "expire_time": "1474982979"
    }
  }
}
// in case of incorrect data
{
  "status": "ERROR",
  "msg": "Wrong credentials"
}

Downloading the list of the shortened links

The list of shortened links assigned to the account that is logged is obtained by sending a request GET to the address link/index. By default, 10 items are returned, you can change the number of items per page by adding a parameter per_page. If you don't use the parameter page the first page is returned.

Parametry

Parameter	Type	Required	Description
page	integer	No	Page number pagination (default 1)
per_page	integer	No	Number of records per page (max. 100)

Return

it returns json containing the pagination data and the links.

If the session has expired the following error is received: Auth token expired.

Errors

Reply	Description
Missing Authorization header key	'Authorization' header is not passed
Missing Bearer auth token	Missing Bearer word, before token you nedd to put 'Bearer '
Auth token expired	Current session is expired
Invalid auth token	Your ACCESS_TOKEN is invalid

PHP

                       
$token = 'kod received during log in';
function links($token){
    $headers = array();
    $headers[] = 'Authorization: Bearer '.$token;
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://iiv.pl/api/link/index?page=1&per_page=10');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $result = curl_exec($ch);
    return $result;
}

print_r(links($token));

// returns json
{
  "status": "OK",
  "data": {
    "total": 3,
    "per_page": 10,
    "current_page": 1,
    "last_page": 1,
    "next_page_url": null,
    "prev_page_url": null,
    "from": 1,
    "to": 3,
    "data": [
      {
        "id": 1,
        "url": "http://wp.pl",
        "created_at": "2016-09-26 11:44:25",
        "updated_at": "2016-09-26 11:44:25",
        "shortcut": "https://iiv.pl/GHVUJ"
      },
      {
        "id": 2,
        "url": "http://test.pl",
        "created_at": "2016-09-26 11:45:07",
        "updated_at": "2016-09-26 11:45:07",
        "shortcut": "https://iiv.pl/hfbCZ"
      },
      {
        "id": 8,
        "url": "http://wp.pl",
        "created_at": "2016-09-27 09:35:52",
        "updated_at": "2016-09-27 09:35:52",
        "shortcut": "https://iiv.pl/JIbUv"
      }
    ]
  }
}
// in case of any error it returns status ERROR and description of error

The informations about the shortened link

One will get data about the single shortened link by sending the request GET to the address link/show/:id. Parameter :id jest required, and it means ID of the shortened link in the system.

Parameters

Parameter	Type	Required	Description
id	integer	Yes	ID of the shortened link in the system

Reply

It returns json containing the data of the link.

If the session has expired the following error is received Auth token expired.

Errors

Reply	Description
Link ID is invalid	There is no link with given ID for given user.
Missing Authorization header key	'Authorization' header is not passed
Missing Bearer auth token	Missing Bearer word, before token you nedd to put 'Bearer '
Auth token expired	Current session is expired
Invalid auth token	Your ACCESS_TOKEN is invalid

PHP

                       
$token = kod received during log in';
function link($token){
    $headers = array();
    $headers[] = 'Authorization: Bearer '.$token;
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://iiv.pl/api/link/show/1');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $result = curl_exec($ch);
    return $result;
}

print_r(link($token));

// returns json
{
  "status": "OK",
  "data": {
    "id": 1,
    "url": "http://wp.pl",
    "created_at": "2016-09-26 11:44:25",
    "updated_at": "2016-09-26 11:44:25",
    "shortcut": "https://iiv.pl/GHVUJ",
    "ad": "1"
  }
}
// in case of any error it returns status ERROR and description of error

Create shortcut link

You can create shortcut link sendiing POST request to link/create. You need to include as a parameter destination url, which is url link to create a shortcut. You can add optional parameter named: new, with value 0 or 1.The new parameter sets option to create either new shortcut or retrieve existing attached to provided url, if there is any (links are attached to account and every single accout has it own links for the same urls).

Parameters

Parameter	Type	Required	Description
url	string	Yes	Url link to create shortcut
new	integer	No	Generate a new shortcut (value 0\|1, default 0)
ad	integer	No	Set this parameter to 0 if you do not want to show ad (1\|0, default 1)

Response

It returns json, containing details about shortcut.

If your session is expired you receive error Auth token expired.

Errors

Odpowiedź	Opis
Url is not valid	Url is not a valid url
Missing Authorization header key	'Authorization' header is not passed
Missing Bearer auth token	Missing Bearer word, before token you nedd to put 'Bearer '
Auth token expired	Current session is expired
Invalid auth token	Your ACCESS_TOKEN is invalid

PHP

                       
$token = 'kod received during log in';
function createLink($token){
    $postfields = array('url'=>'www.cut.so', 'new'=>1, 'ad'=>0);
    $headers = array();
    $headers[] = 'Authorization: Bearer '.$token;
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://iiv.pl/api/link/create');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_POST, 1);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $result = curl_exec($ch);
    return $result;
}

print_r(createLink($token));

// returns json
{
  "status": "OK",
  "data": {
    "url": "http://www.cut.so",
    "ad": "0",
    "updated_at": "2016-09-27 15:34:53",
    "created_at": "2016-09-27 15:34:53",
    "id": "11",
    "shortcut": "https://iiv.pl/uKkBT"
  }
}
// in case of any error it returns status ERROR and description of error

Account info

You can obtain detailed account information by sending GET to address user/info. We will get information about the currently logged in user.

Reply

It returns json containing the account data.

If the session has expired the error will appear Auth token expired.

Errors

Reply	Description
Missing Authorization header key	'Authorization' header is not passed
Missing Bearer auth token	Missing Bearer word, before token you nedd to put 'Bearer '
Auth token expired	Current session is expired
Invalid auth token	Your ACCESS_TOKEN is invalid

PHP

                       
$token = 'kod received during log in';
function userInfo($token){
    $headers = array();
    $headers[] = 'Authorization: Bearer '.$token;
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://iiv.pl/api/user/info');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $result = curl_exec($ch);
    return $result;
}

print_r(userInfo($token));

// returns json
{
  "status": "OK",
  "data": {
    "email": "[email protected]",
    "activated_at": "2016-09-28 07:57:36",
    "last_login": "2016-09-28 09:47:39",
    "created_at": "2016-09-28 07:55:31",
    "updated_at": "2016-09-28 07:57:36"
  }
}
// in case of any error it returns status ERROR and description of error

Change password

You can change password sending POST request to user/change/password. There are some required parameters: password - current password, new_password - new password, email - email address of our account. You need also include ACCESS_TOKEN in headers.

If you forget your password and you do not have ACCESS_TOKEN you need to reset your password matching your email address. You can reset password here

Parameters

Parameter	Type	Required	Description
password	string	Yes	Current password
new_password	string	Yes	New password
email	string	Yes	Email address of your account

Response

Returns json, with status.

Errors

Message	Description
Incorrect new password	Your password may include invalid characters (min. 4 chars)
Missing Authorization header key	'Authorization' header is not passed
Missing Bearer auth token	Missing Bearer word, before token you nedd to put 'Bearer '
Auth token expired	Current session is expired
Invalid auth token	Your ACCESS_TOKEN is invalid

PHP

                       
$token = 'kod received during log in';
function changePassword($token){
    $postfields = array(
       'password'=>'oldpassword',
       'new_password'=>'newpassword',
       'email'=>'[email protected]');
    $headers = array();
    $headers[] = 'Authorization: Bearer '.$token;
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://iiv.pl/api/link/create');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_POST, 1);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $result = curl_exec($ch);
    return $result;
}

print_r(changePassword($token));

// returns json
{
  "status": "OK"
}
// in case of any error it returns status ERROR and description of error

Account registration

The account can be registered by sending the request POST to the address user/register. The required parameters are email - e-mail address, password - password, terms - the acceptance of terms of service should be 1.

Parameters

Parameter	Type	Required	Description
email	string	Yes	E-mail address
password	string	Yes	Password
terms	integer	Yes	The acceptance of the terms of the service (should be 1)
lang	string	No	Language (pl,en) default pl

Reply

It returns json containing the status of operation and the message.

Errors

Reply	Description
Invalid fields	Incorrect data, the list of errors: 'errors'
System error	System error
Registration is unavailable	Registration is temporarily unavailable

PHP

                       
$token = 'kod received during log in';
function register(){
    $postfields = array(
       'email'=>'[email protected]',
       'password'=>'Password',
       'terms'=>1);
    $headers = array();
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://iiv.pl/api/user/register');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_POST, 1);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $result = curl_exec($ch);
    return $result;
}

print_r(register($token));

// returns json
{
  "status": "OK",
  "msg": "Activation email is sent"
}
// in case of any error it returns status ERROR and description of error
// if any validation errors it returns additional errors

Logging out

You can log out using the command auth/logout. It is induced by POST method. In the header we set ACESS_TOKEN as: Authorization: Bearer ACCESS_TOKEN

Keep in mind that signing off after working with the API is related to security. ACCESS_TOKEN is valid for 60 minutes after logging in and is assigned to the IP address from which the logging occurred. To improve the security, after completing the API, you must finish the session properly by properly logging out.

Reply

It returns json containing the status of operation.

Błędy

Reply	Description
Missing Authorization header key	'Authorization' header is not passed
Missing Bearer auth token	Missing Bearer word, before token you nedd to put 'Bearer '
Auth token expired	Current session is expired
Invalid auth token	Your ACCESS_TOKEN is invalid

PHP

                       
$token = 'kod received during log in';
function logout($token){
    $headers = array();
    $headers[] = 'Authorization: Bearer '.$token;
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://iiv.pl/api/auth/logout');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $result = curl_exec($ch);
    return $result;
}
print_r(logout($token));
// returns
{"status":"OK"}
// in case of any error it returns status ERROR and description of error

Session

We get the data about each session using the command session. The request is sent using the method POST with no parameters. The only thing one has to do is to send Authorization: Bearer ACCESS_TOKEN as the headline.

Reply

It returns json containing data session.

If the session has expired the error will appear Auth token expired.

Errors

Reply	Description
Missing Authorization header key	'Authorization' header is not passed
Missing Bearer auth token	Missing Bearer word, before token you nedd to put 'Bearer '
Auth token expired	Current session is expired
Invalid auth token	Your ACCESS_TOKEN is invalid

PHP

                       
$token = 'kod received during log in';
function session($token){
    $headers = array();
    $headers[] = 'Authorization: Bearer '.$token;
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://iiv.pl/api/auth/session');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $result = curl_exec($ch);
    return $result;
}

print_r(session($token));

// returns json
{
  "status": "OK",
  "data": {
    "session": {
      "ip": "127.0.0.1",
      "token": "aoYeZh6BYUVEbvtbaP2bHn2mMXg2QcD4",
      "expire_time": 1474985043
    }
  }
}
// in case of any error it returns status ERROR and description of error