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 http://cut.so/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:

  1. Log in to system using email and password
  2. Log out
  3. Retrieve shortcut links list
  4. Create shortcuts
  5. Retrieve details about shortcut link
  6. Access account details
  7. Change account password
  8. Register new accounts
  9. 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, 'http://cut.so/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'=>'test@example.com', 'password'=>'yoursecretpassword');
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, 'http://cut.so/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"
}
						
						
PHP
                       
$token = 'kod received during log in';
function links($token){
    $headers = array();
    $headers[] = 'Authorization: Bearer '.$token;
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'http://cut.so/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": "http://cut.so/GHVUJ"
      },
      {
        "id": 2,
        "url": "http://test.pl",
        "created_at": "2016-09-26 11:45:07",
        "updated_at": "2016-09-26 11:45:07",
        "shortcut": "http://cut.so/hfbCZ"
      },
      {
        "id": 8,
        "url": "http://wp.pl",
        "created_at": "2016-09-27 09:35:52",
        "updated_at": "2016-09-27 09:35:52",
        "shortcut": "http://cut.so/JIbUv"
      }
    ]
  }
}
// in case of any error it returns status ERROR and description of error
                        
                        
PHP
                       
$token = kod received during log in';
function link($token){
    $headers = array();
    $headers[] = 'Authorization: Bearer '.$token;
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'http://cut.so/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": "http://cut.so/GHVUJ",
    "ad": "1"
  }
}
// in case of any error it returns status ERROR and description of error
                        
                        
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, 'http://cut.so/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": "http://cut.so/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, 'http://cut.so/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": "test@example.com",
    "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'=>'test@example.com');
    $headers = array();
    $headers[] = 'Authorization: Bearer '.$token;
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'http://cut.so/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'=>'test@example.com',
       'password'=>'Password',
       'terms'=>1);
    $headers = array();
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'http://cut.so/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, 'http://cut.so/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, 'http://cut.so/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