Workflow API Authentication¶

Overview¶

With the API made available by ResIOT you have access to many features of the platform, from the simple creation of a node, up to the management of sub accounts.

Structure¶

Methods¶

Among our API there are four different methods:

GET:

Given an input, GET calls respond with a list of specific data regarding the requested device or the requested action;
POST:

POST calls allow you to create devices and actions, specifying all the data required for input, within ResIOT;
PUT:

Given an identifier and some data concerning the device / action, these calls allow to modify an instance already present on the platform;
DELETE:

As is understandable, this call allows you to delete a specific instance from ResIOT.

Authentication¶

Most of our APIs need a unique token called "RESTful API V3 Token" to work properly.
This token can be found within the user's options, specifically in the "Settings" menu and immediately after "My Settings" you can find it under the name "RESTful API V3 Token".
Token
Each token is unique for each user, in this way we can identify the account that is making the API call, thus being able to block, if necessary, the operations of the call if the user in question does not have the appropriate permissions.

Header Settings
In addition to the token, an API call to work also needs other headers.
Below you will find a json with an example of headers:

{
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Grpc-Metadata-Authorization": "<<YOUR RESTful API V3 Token>>",
}

Depending on the type of call, you can also have just some of the headers written above.

Body¶

For some calls you need to send a lot of data with the call, usually in POST and PUT, and to do this you must send, in addition to the header presented above, also a field "Data".
In each call it will be explained what extra data will have to be added, otherwise, if nothing is specified, then it will not be necessary to send this field.

-- Example of Body from the API "POST /api/applications"
{
  "appEUI": "string",
  "name": "string"
}

Response¶

Once the call reaches its end, the user returns an answer that can be successful or negative.
In case of a negative result, the call will send an error code with a quick explanation of the same, otherwise if everything is successful, it can send either an empty json, or a list of data related to the requested action.

-- Error Message
{
  "error": "Error message.",
  "message": "Error message.",
  "code": 2
}

-- Successfull message 1
{}

-- Successfull message 2 -- Example from the API "GET /api/applications" with "limit" and "offset" at 0
{
  "totalCount": "51"
}

Examples¶

Below are some examples of calls with different case studies.

Get "RESTful API V3 Token"¶

Token

If you do not have access to your "RESTful API V3 Token" then you can call this API, which returns the token in return for your account credentials.

PHP Example

$URL = '<Your URL>'; // The URL of your service, Example: "https://eu72.resiot.io"
$Username = '<Your Username>'; // The Username that you use to login in into ResIOT
$Password = '<Your Password>'; // The Password that you use to login in into ResIOT
$Curl = curl_init($URL.'/api/user/gettoken/api/'.$Username.'/'.$Password); // Set up a connection to the server.

$Header = array(); // Initialize Headers
$Header[] = 'Accept: application/json';
curl_setopt($Curl, CURLOPT_HTTPHEADER, $Header);
curl_setopt($Curl, CURLOPT_RETURNTRANSFER, true);

$Response = curl_exec($Curl); // Call the API
curl_close($Curl); // Close the connection

$Obj = json_decode($Response); // Parse the Resulting JSON
echo $Obj->{'Token'}; // Print the resulting Token

Angularjs Example

var URL = '<Your URL>'; // The URL of your service, Example: "https://eu72.resiot.io"
var Username = '<Your Username>'; // The Username that you use to login in into ResIOT
var Password = '<Your Password>'; // The Password that you use to login in into ResIOT

$http({ // Call the API
    url: URL + "/api/user/gettoken/api/"+Username+"/"+Password, // Set URL
    method: "GET", // Set Method
    headers: { // Set Headers
        "Accept": "application/json",
    },
}).then(function successCallback(response) { // In case of Success
    alert(response.data.Token); // Print the resulting Token
}, function errorCallback(response) { // In case of Error
    // Do Something Else
});

Get Applications¶

Application

Get the list of applications you have.

PHP Example

    $URL = '<Your URL>'; // The URL of your service, Example: "https://eu72.resiot.io"
    $Token = '<Your RESTful API V3 Token>'; // You can find this token in the "My Settings" page of the "Settings" menu, or in the "RESTful API V3" page of the "Tutorial" menu
    $Limit = '<Limit>'; // This value indicates the amount of instances that will be given in response, if the value is 0, only the "totalCount" will be shown
    $Offset = '<Offset>'; // This value indicates the number of instances to be skipped
    $Curl = curl_init($URL.'/api/applications?limit='.$Limit.'&offset='.$Offset); // Set up a connection to the server.

    $Header = array(); // Initialize Headers
    $Header[] = 'Accept: application/json';
    $Header[] = 'Grpc-Metadata-Authorization: '.$Token;
    curl_setopt($Curl, CURLOPT_HTTPHEADER, $Header);
    curl_setopt($Curl, CURLOPT_RETURNTRANSFER, true);
    $Response = curl_exec($Curl); // Call the API
    curl_close($Curl); // Close the connection

    $Obj = json_decode($Response);  // Parse the Resulting JSON
    $List = $Obj->{'result'};
    foreach ($List as $Application) { // Cycle the list of Applications
        echo $Application->{'appEUI'}.'<br>';
    }

Angularjs Example

var URL = '<Your URL>'; // The URL of your service, Example: "https://eu72.resiot.io"
var Token = '<Your RESTful API V3 Token>'; // You can find this token in the "My Settings" page of the "Settings" menu, or in the "RESTful API V3" page of the "Tutorial" menu
var Limit = '<Limit>'; // This value indicates the amount of instances that will be given in response, if the value is 0, only the "totalCount" will be shown
var Offset = '<Offset>'; // This value indicates the number of instances to be skipped

$http({ // Call the API
    url: URL + "/api/applications?limit="+Limit+"&offset="+Offset, // Set URL
    method: "GET", // Set Method
    headers: { // Set Headers
        "Accept": "application/json",
    },
}).then(function successCallback(response) { // In case of Success
    for(var i=0;i<response.data.result.length;i++){ // Cycle the list of Applications
        alert(response.data.result[i].appEUI)
    }
}, function errorCallback(response) { // In case of Error
    // Do Something Else
});

Post Application¶

Application

Create a new Application.

PHP Example

$URL = '<Your URL>'; // The URL of your service, Example: "https://eu72.resiot.io"
$Token = '<Your RESTful API V3 Token>'; // You can find this token in the "My Settings" page of the "Settings" menu, or in the "RESTful API V3" page of the "Tutorial" menu
$App_Name = '<The Application Name>'; // The name you want to give at your Application
$AppEUI = '<The Application EUI>'; // The name you want to give at your Application
$Curl = curl_init($URL.'/api/applications'); // Set up a connection to the server.

$Header = array(); // Initialize Headers
$Header[] = 'Content-Type: application/json';
$Header[] = 'Accept: application/json';
$Header[] = 'Grpc-Metadata-Authorization: '.$Token;
curl_setopt($Curl, CURLOPT_HTTPHEADER, $Header);
curl_setopt($Curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($Curl, CURLOPT_POST, true); // Here it is specified that it is a POST call

$curl_post_data = array( // Creation of the body
    'appEUI' => $AppEUI,
    'name' => $App_Name
);
curl_setopt($Curl, CURLOPT_POSTFIELDS, json_encode($curl_post_data)); // Set the body into the call

$Response = curl_exec($Curl); // Call the API
curl_close($Curl); // Close the connection
$Obj = json_decode($Response);  // Parse the Resulting JSON
echo $Obj->{'appEUI'}; // Print the response

Angularjs Example

var URL = '<Your URL>'; // The URL of your service, Example: "https://eu72.resiot.io"
var Token = '<Your RESTful API V3 Token>'; // You can find this token in the "My Settings" page of the "Settings" menu, or in the "RESTful API V3" page of the "Tutorial" menu
var App_Name = '<The Application Name>'; // The name you want to give at your Application
var AppEUI = '<The Application EUI>'; // The name you want to give at your Application

$http({ // Call the API
    url: URL + "/api/applications", // Set URL
    method: "POST", // Set Method
    headers: { // Set Headers
        "Accept": "application/json",
    },
    data: { // Set Body
        "appEUI": AppEUI,
        "name": App_Name
    }
}).then(function successCallback(response) { // In case of Success
    alert(response.data.result.appEUI) // Print the response
}, function errorCallback(response) { // In case of Error
    // Do Something Else
});