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
.
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:
// 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);
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.
login
again, it generates new ACCESS_TOKEN
Parameter | Type | Required | Description |
---|---|---|---|
string | Yes | E-mail address | |
password | string | Yes | Password |
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
Reply | Description |
---|---|
Empty credentials | One parameter is missing |
Wrong credentials | Incorrect login parameters |
function login(){
$postfields = array('email'=>'[email protected]', '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"
}
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.
Parameter | Type | Required | Description |
---|---|---|---|
page | integer | No | Page number pagination (default 1) |
per_page | integer | No | Number of records per page (max. 100) |
it returns json
containing the pagination data and the links.
Auth token expired
.
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 |
$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
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.
Parameter | Type | Required | Description |
---|---|---|---|
id | integer | Yes | ID of the shortened link in the system |
It returns json
containing the data of the link.
Auth token expired
.
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 |
$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
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).
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) |
It returns json
, containing details about shortcut.
Auth token expired
.
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 |
$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
You can obtain detailed account information by sending GET
to address user/info
. We will get information about the currently logged in user.
It returns json
containing the account data.
Auth token expired
.
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 |
$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": "[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
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.
ACCESS_TOKEN
you need to reset your password matching your email address. You can reset password here
Parameter | Type | Required | Description |
---|---|---|---|
password | string | Yes | Current password |
new_password | string | Yes | New password |
string | Yes | Email address of your account |
Returns json
, with status.
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 |
$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, '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
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
.
Parameter | Type | Required | Description |
---|---|---|---|
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 |
It returns json
containing the status of operation and the message.
Reply | Description |
---|---|
Invalid fields | Incorrect data, the list of errors: 'errors' |
System error | System error |
Registration is unavailable | Registration is temporarily unavailable |
$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, '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
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
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.
It returns json
containing the status of operation.
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 |
$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
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.
It returns json
containing data session.
Auth token expired
.
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 |
$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