REST API Examples

This guide describes fundamental concepts used with the RIoT Secure REST API along with code examples in PHP that demonstrate common programming techniques.

1. Basic Concepts

1.1. Object Types

There are two types of objects stored in the OASIS Cloud:

• Entities - objects that consists of data fields (keys) that can have subobjects. As a general rule, entities can be updated. Specific entity fields can be read only.

• Assets - objects that represent data stored as files, for example firmware files and images. Assets cannot be updated once created, all asset fields are read only.

1.2. Routes

The REST API consists of a number of routes. Each route corresponds to a call that provides access to a particular object in the OASIS Cloud.

Example:

This route retrieves information about available firmwares for the tenant with id 3:

GET tenant/3/firmware_appl

The REST API supports calling routes with different request methods (GET/POST/PUT/DELETE). This basic guide covers GET requests. The REST API Advanced Guide covers all request metods.

A list of all available routes is given in the REST API Reference Documentation.

Most routes return JSON data in the response. Several routes also take input in the form of JSON data.

1.3. Request Methods

REST API routes return information about objects (entities), and/or create or update objects. The HTTP request type determines the specific functionality performed.

A route can be called with different HTTP request methods to perform different functions:

Note that not all request methods are available for all routes. Consult the REST API Reference Documentation for details regarding each route.

1.4. Tenants

A tenant represents an entity that has a dedicated space in the OASIS Cloud. A tenant can have one or more users.

Users, devices, packet definitions, and application firmwares, are objects that belong to a particular tenant.

The tenant id is required for for the /tenant family of routes. This id is provided in the JSON response data from the /auth route, in the field id_tenant.

1.5 The expand Parameter

A GET request typically returns data (JSON) in the response. When the expand parameter is included with the request, the response will be expanded to include all fields and sub fields of the object. This option is supported for routes that return an object or an array of objects.

Example:

This route returns a JSON array with ids of available devices for the tenant with id 3:

GET tenant/3/device

This route returns a JSON array with all devices expanded; each array element is a JSON object representing all data about a device:

GET tenant/3/device?expand

IMPORTANT: The “?expand” part of the URI must not be present when computing the Authorization header token.

1.6. Response Header

When using the cURL library to make HTTP requests, the response is typically returned as a string. This string may for example consist of JSON data.

The cURL library contains an option for including the response header with the response string. This option can be useful for learning and debugging, but it should NOT be used for code that parses JSON data (since the header data is not valid JSON).

To handle errors and retrieve the HTTP response code, the cURL library has methods for this.

PHP documentation for cURL: www.php.net/manual/en/ref.curl.php

1.7. The /auth Route

The /auth route returns a JSON object with the credentials for the current user (as provided in the Authorization header). This is useful for inspecting and validating the permissions of the current user; and for obtaining the tenant id.

It should be noted that the /auth route is like any other route; it is not for authorization or login, but is used to retrieve information about the user.

The /auth route does not use the expand parameter (the returned result is already “expanded”).

1.8. Tenant Id

Importantly, the /auth response returns the tenant id in the field id_tenant. This id is required for for the /tenant family of routes.

1.9. Permissions

Each route requires a certain permission level. The /auth route can be used to determine the permissions for the current user.

2. REST API Library

The code examples in this guide use a library for making REST API requests to fetch, create, update and delete objects in the OASIS Cloud.

The code in this guide is intended for learning - it is not for production use. In production code, make sure to validate input and handle errors properly.

2.1. Library Code

File tools/lib/rest_api_lib.php contains a library with functions for making different kinds of REST API requests. This library is useful for learning and experimenting with the REST API.

Here is the code for the library (click to view):

<?php
/*
Library for learning the OASIS REST API.

NOT for production use. Intended for educational purposes.

Error handling and other aspects of the library should be
improved for production use.
*/

require_once __DIR__ . "/authorization_lib.php";

// --------------------------------------------------------------
// GLOBALS AND CONSTANTS
// --------------------------------------------------------------

$_SERVER_URL          = null;
$_AUTH_METHOD         = null;
$_USERNAME            = null;
$_PASSHASH            = null;

$_CURL_ERRNO          = 0;
$_CURL_ERROR          = null;
$_HTTP_RESPONSE_CODE  = null;

// Constants for query options
define("OPT_NONE",           1);  // No options set
define("OPT_EXPAND",         2);  // Set the the expand parameter
define("OPT_HEADER_INCLUDE", 4);  // Include header and body in response
define("OPT_HEADER_ONLY",    8);  // Include header only in response
// Default is to include only the body in the response

// --------------------------------------------------------------
// CONFIG FUNCTIONS
// --------------------------------------------------------------

// Set the server URL
function rest_api_set_server_url($server_url)
{
  global $_SERVER_URL;

  $_SERVER_URL = $server_url;
}

// Set user credentials used for authentication
// Note this function only accepts a password hash
function rest_api_set_user_credentials(
  $username,
  $passhash,
  $auth_method = "oasis")
{
  global $_AUTH_METHOD;
  global $_USERNAME;
  global $_PASSHASH;

  $_AUTH_METHOD = $auth_method;
  $_USERNAME    = $username;
  $_PASSHASH    = $passhash;
}

// Read and pars the specified JSON file
function rest_api_read_config_file($path)
{
  $json = file_get_contents($path);
  if (false === $json)
  {
    echo "[rest_api_lib.php] Fatal Error: Could not read JSON file: {$path}".PHP_EOL;
    die();
  }

  // TODO: Error check decode
  $obj = json_decode($json);

  return $obj;
}

// Read the specified config file and set user credentials
function rest_api_read_login_config($path)
{
  $obj = rest_api_read_config_file($path);

  rest_api_set_server_url($obj->server_url);

  rest_api_set_user_credentials(
    $obj->username,
    $obj->passhash,
    $obj->auth_method);
}

// --------------------------------------------------------------
// UTILITY FUNCTIONS
// --------------------------------------------------------------

// Return absolute path based on relative or absolute path name
function get_absolute_path($file_name)
{
  // Check if absolute path (begins with "/")
  if ($file_name[0] === "/")
  {
    // Absolute path - use as is
    return $file_name;
  }
  else
  {
    // Assume relative path
    return getcwd() . "/" . $file_name;
  }
}

// --------------------------------------------------------------
// QUERY FUNCTIONS
// --------------------------------------------------------------

// Generic REST API request function
function rest_api_request(
  $request_method,
  $request_uri,
  $options = OPT_NONE,
  $data = null,
  $content_type = null)
{
  $curl = rest_api_create_query($request_method, $request_uri, $options, $data, $content_type);
  $response = rest_api_curl_exec($curl);
  curl_close($curl);

  return $response;
}

// Make a GET request
function rest_api_get($request_uri)
{
  return rest_api_request("GET", $request_uri);
}

// Make a GET request with the expand query parameter set
function rest_api_get_expand($request_uri)
{
  return rest_api_request("GET", $request_uri, OPT_EXPAND);
}

// Make a POST request
function rest_api_post($request_uri, $data, $content_type)
{
  return rest_api_request("POST", $request_uri, OPT_NONE, $data, $content_type);
}

// Make a PUT request
function rest_api_put($request_uri, $data, $content_type)
{
  return rest_api_request("PUT", $request_uri, OPT_NONE, $data, $content_type);
}

// Make a DELETE request
function rest_api_delete($request_uri)
{
  return rest_api_request("DELETE", $request_uri);
}

// Make a OPTIONS request
function rest_api_options($request_uri)
{
  return rest_api_request("OPTIONS", $request_uri);
}

// Make an OPTIONS request to get the response HEADER only
function rest_api_options_header($request_uri)
{
  return rest_api_request("OPTIONS", $request_uri, OPT_HEADER_ONLY);
}

// Make a OPTIONS preflight request (only header returned)
function rest_api_options_preflight($request_uri, $request_method, $request_headers)
{
  $request_method = "OPTIONS";

  $url = rest_api_url($request_uri, OPT_NONE);
  $curl = curl_init($url);

  // Preflight request headers
  $header =
  [
    "origin: " . $url,
    "access-control-request-method: " . $request_method,
    "access-control-request-headers: " . $request_headers
  ];

  // Include response header
  check_curlopt(curl_setopt($curl, CURLOPT_HEADER, true));

  // Set common options
  check_curlopt(curl_setopt($curl, CURLOPT_HTTPHEADER, $header));
  check_curlopt(curl_setopt($curl, CURLOPT_RETURNTRANSFER, true));
  check_curlopt(curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $request_method));
  check_curlopt(curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true));

  $response = rest_api_curl_exec($curl);

  curl_close($curl);

  return $response;
}

// Get the tenant id of the current user
function rest_api_tenant_get_id()
{
  $response_json = rest_api_get("/auth");
  $info = json_decode($response_json);
  return $info->id_tenant;
}

// --------------------------------------------------------------
// ERROR FUNCTIONS
// --------------------------------------------------------------

// Returns last HTTP response code
function rest_api_get_http_response_code()
{
  global $_HTTP_RESPONSE_CODE;
  return $_HTTP_RESPONSE_CODE;
}

// Returns last HTTP response
function rest_api_get_http_response()
{
  global $_HTTP_RESPONSE;
  return $_HTTP_RESPONSE;
}

// Returns last cURL error number
function rest_api_get_curl_errno()
{
  global $_CURL_ERRNO;
  return $_CURL_ERRNO;
}

// Returns last cURL error message
function rest_api_get_curl_error()
{
  global $_CURL_ERROR;
  return $_CURL_ERROR;
}

// --------------------------------------------------------------
// QUERY HELPER FUNCTIONS
// --------------------------------------------------------------

// Returns cURL object
function rest_api_create_query(
  $request_method,
  $request_uri,
  $options = OPT_NONE,
  $data = null,
  $content_type = null)
{
  $url = rest_api_url($request_uri, $options);

  $curl = curl_init($url);

  // Query header entries
  $header = [];

  // Set auth header entry
  $auth_header = rest_api_auth_header($request_method, $request_uri);
  array_push($header, $auth_header);

  // Set content type header
  if (null !== $content_type)
  {
    array_push($header, "Content-type: " . $content_type);
  }

  // Set data for POST and PUT.
  if ($data !== null)
  {
    check_curlopt(curl_setopt($curl, CURLOPT_POSTFIELDS, $data));
  }

  // Common cURL options
  check_curlopt(curl_setopt($curl, CURLOPT_HTTPHEADER, $header));
  check_curlopt(curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $request_method));
  check_curlopt(curl_setopt($curl, CURLOPT_RETURNTRANSFER, true));
  check_curlopt(curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true));

  // Set header include/exclude options
  if ($options & OPT_HEADER_INCLUDE)
  {
    check_curlopt(curl_setopt($curl, CURLOPT_HEADER, true));
  }
  else
  if ($options & OPT_HEADER_ONLY)
  {
    check_curlopt(curl_setopt($curl, CURLOPT_HEADER, true));
    check_curlopt(curl_setopt($curl, CURLOPT_NOBODY, true));
  }

  return $curl;
}

function rest_api_url($request_uri, $options)
{
  global $_SERVER_URL;

  $url = $_SERVER_URL . $request_uri;
  if ($options & OPT_EXPAND)
  {
    $url .= "?expand";
  }

  return $url;
}

// Check the return value from curl_setopt
function check_curlopt($success)
{
  if (!$success)
  {
    echo "[rest_api_lib.php] Fatal Error: curl_setopt() failed".PHP_EOL;
    die();
  }
}

// Perform query and return response
// Return false on cURL error
// Use error functions to get error information
function rest_api_curl_exec($curl)
{
  global $_CURL_ERRNO;
  global $_CURL_ERROR;
  global $_HTTP_RESPONSE_CODE;
  global $_HTTP_RESPONSE;

  $_CURL_ERRNO         = 0;
  $_CURL_ERROR         = null;
  $_HTTP_RESPONSE_CODE = null;

  $response = curl_exec($curl);

  $http_response_code = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
  $_HTTP_RESPONSE_CODE = $http_response_code;
  $_HTTP_RESPONSE = $response;

  $errno = curl_errno($curl);
  if ($errno !== 0)
  {
    $error = curl_error($curl);
    $_CURL_ERRNO = $errno;
    $_CURL_ERROR = $error;

    return false;
  }

  return $response;
}

// Return auth header string
function rest_api_auth_header($request_method, $request_uri)
{
  global $_USERNAME;
  global $_PASSHASH;

  return rest_api_authorization_header(
    $_USERNAME,
    $_PASSHASH,
    $request_method,
    $request_uri);
}

// --------------------------------------------------------------
// RESPONSE PARSING FUNCTIONS
// --------------------------------------------------------------

// Get the header part of full response
function rest_api_response_header($response)
{
  $pos = strpos($response, "\r\n\r\n");
  if ($pos !== false)
  {
    $header = substr($response, 0, $pos);
  }
  else
  {
    $header = "";
  }

  return $header;
}

// Get the body part of full response
function rest_api_response_body($response)
{
  $pos = strpos($response, "\r\n\r\n");
  if ($pos !== false)
  {
    $header = substr($response, $pos + 4);
  }
  else
  {
    $body = "";
  }

  return $body;
}

// Returns reponse headers as a dictionary (array with keys and values)
function rest_api_parse_response_headers($response_header)
{
  $headers = [];

  $lines = explode("\n", $response_header);

  foreach($lines as $line)
  {
    $parts = explode(":", $line, 2);

    // Include header if $parts[1] exist
    if (isset($parts[1]))
    {
      $key = strtolower(trim($parts[0]));
      $value = trim($parts[1]);
      $headers[$key] = $value;
    }
  }

  return $headers;
}

// It is considered best practice to not close the <?php tag
// in a PHP-only file.

2.2. Library Functions

Function that reads the login config file:

rest_api_read_login_config($path)

Request functions:

rest_api_get($request_uri)
rest_api_get_expand($request_uri)
rest_api_post($request_uri, $post_data, $content_type)
rest_api_put($request_uri, $json_data)
rest_api_delete($request_uri)

Function to get the tenant id:

rest_api_tenant_get_id()

Function to get error status:

rest_api_get_http_response_code()

2.3. Login Config File

The REST API library also supports the use of a login config file.

In order to separate sensitive data (user credentials) from the source code, the library supports the use of a login config file.

2.3.1. REST API Authentication Scheme

It should be noted that the REST API does not use login in the usual sense; rather a set of tokens that contains hashed authentication data is provided with every request (as a header field). This makes for a higly secure and straightforward authentication scheme.

A web client, for example, would however employ a login procedure and keep user credentials during the active session.

2.3.2. Login Config File Format

The login config file has the following format (replace placeholders with actual values):

{
  "server_url" : "https://demo.riotsecure.io:6443",
  "auth_method" : "oasis",
  "username" : "USERNAME",
  "passhash" : "PASSHASH"
}

Note that the password itself is not stored. Rather, a password hash is used. See information below for how to compute the password hash.

2.3.3. Password Hash Tool

To create a password hash, a command-line tool is provided. This tool is available in file tools/passhash/passhash.php.

<?php
/*
File: passhash.php

Generate the password hash token used in the REST API login config file.

Outputs the login token. Copy and paste this token into the login.json file.

Usage:

    php passhash.php USERNAME PASSWORD

Example command and output:

    php passhash.php "user@email.com" "mysecretpassword"
    D7E483322282838AD065CE815D5EE05F
*/

require_once __DIR__ . "/../lib/authorization_lib.php";

if ($argc != 3)
{
  echo "Create a password hash token" . PHP_EOL;
  echo "Usage:" . PHP_EOL;
  echo "php passhash.php \"username\" \"password\"" . PHP_EOL;
}
else
{
  $username = $argv[1];
  $password = $argv[2];
  echo rest_api_passhash($username, $password) . PHP_EOL;
}

Usage example and encoded result:

php tools/passhash/passhash.php "user@email.com" "mysecretpassword"
D7E483322282838AD065CE815D5EE05F

Paste the password hash into the config file.

Example of use:

2.3.4. Version Control and Login Credentials

Make sure to keep the login config file private. Exclude this file from version control and backup systems that could compromise the data.

In the git version control system, the .gitignore file can be edited to exclude the login config file from version control. This practice helps to prevent the file from ending up on external servers when using git.

3. Working With JSON

JSON is an essential part of the REST API. PHP has convinient functions for encoding and decoding JSON data.

JSON is a string format. A common use case for JSON is to return objects or arrays of objects in response to a GET request.

3.1. Decode JSON

Function json_decode() is used to decode JSON strings. The return value is a PHP array or object.

Example:

$response = rest_api_get_expand("/microcontroller");
$microcontroller_array = json_decode($response);

3.2. Encode JSON

Function json_encode() encodes a PHP array or object as a JSON string.

The REST API server expects the JSON encoding option JSON_UNESCAPED_SLASHES.

Example:

$data = ["foo" => "bar"];
$json = json_encode($data, JSON_UNESCAPED_SLASHES);

3.3. Error Handling

Production code should check JSON encode/decode for errors.

Function json_last_error() returns an int representing an an error code. JSON_ERROR_NONE means no error.

To get a string describing the error, the function json_last_error_msg() is used.

Example:

$obj = json_decode("foo: bar");
if (JSON_ERROR_NONE !== json_last_error())
{
  echo "JSON ERROR: " . json_last_error_msg() . "\n";
}

4. Code Examples

This section has examples of PHP command-line scripts that call the REST API.

Note that these are not server-side scripts called from a web browser, by scripts that are run locally from the command line.

4.1. Preparation

Install PHP on your local machine (if not done already). This makes the PHP interpreter available from the command line.

Create a login config file (according to the above instructions). You can name it as you wish - it is provided as a script parameter.

Run the example programs from the command line and specify the login config file as a parameter. The path to the config file is relative to the current working directory.

Here are some examples:

php guide/examples/modem_get.php mylogin.json
php guide/examples/microcontroller_get.php mylogin.json
php guide/examples/global_get.php mylogin.json

4.2. Basic GET Request (modem)

This example uses GET to obtain an array of modem objects. The script prints the unparsed JSON data.

<?php
/*
File: modem_get.php

This example uses a GET request to get data about modems.

The returned JSON data is printed in raw unparsed format.

Usage:

    php modem_get.php LOGINFILE

Example:

    php modem_get.php mylogin.json
*/

require_once __DIR__ . "/../../tools/lib/rest_api_lib.php";

// Read config file with user credentials
if ($argc == 2)
{
  $login_config_file = $argv[1];
  $config_path = get_absolute_path($login_config_file);
  rest_api_read_login_config($config_path);
}
else
{
  echo "USAGE:" . PHP_EOL;
  echo "php modem_get.php LOGINFILE" . PHP_EOL;
  echo "EXAMPLE:" . PHP_EOL;
  echo "php modem_get.php mylogin.json" . PHP_EOL;
  die();
}

// Get ids of all modems (without expand option)
$response = rest_api_get("/modem");

// Uncomment the following line to make the same request with the expand option
// (comment out the above line)
//$response = rest_api_get_expand("/modem");

// Uncomment the following line to get the single modem with id 3
// (comment out the above lines)
//$response = rest_api_get_expand("/modem/3");

// Display unparsed JSON data
echo $response . PHP_EOL;

// It is considered best practice to not close the <?php tag
// in a PHP-only file.

The printed return value is an unparsed JSON array that contains the ids of the available modems.

When using the expand option, an array of full modem objects is returned.

Experiment with the above source code to make the calls with and without the expand option.

This call returns an array of modem ids:

$response = rest_api_get("/modem");

This call returns an array of modem objects (expand):

$response = rest_api_get_expand("/modem");

This call returns a single modem object with the specified id:

$response = rest_api_get_expand("/modem/3");

Output example:

4.3. Parse Response Data (microcontroller)

This example shows how to use a GET request to retrieve a list of objects as a JSON array, and then parse and access the data. The /microcontroller route is used to retrieve information about microcontrollers supported by the system.

<?php
/*
File: microcontroller_get.php

This example uses a GET request to obtain info about microcontrollers
for the AVR architecture.

The returned JSON data is parsed and printed.

Usage:

    php microcontroller_get.php LOGINFILE

Example:

    php microcontroller_get.php mylogin.json
*/

require_once __DIR__ . "/../../tools/lib/rest_api_lib.php";

// Read config file with user credentials
if ($argc == 2)
{
  $login_config_file = $argv[1];
  $config_path = get_absolute_path($login_config_file);
  rest_api_read_login_config($config_path);
}
else
{
  echo "USAGE:" . PHP_EOL;
  echo "php microcontroller_get.php LOGINFILE" . PHP_EOL;
  echo "EXAMPLE:" . PHP_EOL;
  echo "php microcontroller_get.php mylogin.json" . PHP_EOL;
  die();
}

// Get id:s of all microcontrollers (returns JSON array of objects)
// These are the microcontrollers supported by the system
$response = rest_api_get_expand("/microcontroller");

// Convert JSON to PHP array
$microcontroller_array = json_decode($response);

// Print name and identifier of AVR microcontrollers
echo "AVAILABLE MICROCONTROLLERS FOR THE AVR ARCHITECTURE:" . PHP_EOL;
foreach ($microcontroller_array as $microcontroller)
{
  if ("avr" === $microcontroller->keys->arch)
  {
    if ($microcontroller->id < 10) { echo " "; } // print padding before single digit id
    echo $microcontroller->id . " " . $microcontroller->keys->identifier . " " . $microcontroller->keys->name . PHP_EOL;
  }
}

// It is considered best practice to not close the <?php tag
// in a PHP-only file.

Output example:

4.4. Global Settings (global)

This example uses GET to obtain the global system settings. The script prints the unparsed JSON data. These settings are managed by the system administrator, but can be read by a tenant user.

<?php
/*
File: global_get.php

This example uses a GET request to obtain info about global data.

The returned JSON data is printed in raw unparsed format.

Usage:

    php global_get.php LOGINFILE

Example:

    php global_get.php mylogin.json
*/

require_once __DIR__ . "/../../tools/lib/rest_api_lib.php";

// Read config file with user credentials
if ($argc == 2)
{
  $login_config_file = $argv[1];
  $config_path = get_absolute_path($login_config_file);
  rest_api_read_login_config($config_path);
}
else
{
  echo "USAGE:" . PHP_EOL;
  echo "php global_get.php LOGINFILE" . PHP_EOL;
  echo "EXAMPLE:" . PHP_EOL;
  echo "php global_get.php mylogin.json" . PHP_EOL;
  die();
}

// Get JSON data
$response = rest_api_get_expand("/global");

// Print data (unparsed string data)
echo $response . PHP_EOL;

// It is considered best practice to not close the <?php tag
// in a PHP-only file.

4.5. GET Tenant Info

This example uses GET request information about the tenant for the logged in user. The script prints the unparsed JSON data.

<?php
/*
File: tenant_get.php

This example uses a GET request to obtain info about the tenant.

The returned JSON data is printed in raw unparsed format.

Usage:

    php tenant_get.php LOGINFILE

Example:

    php tenant_get.php mylogin.json
*/

require_once __DIR__ . "/../../tools/lib/rest_api_lib.php";

// Read config file with user credentials
if ($argc == 2)
{
  $login_config_file = $argv[1];
  $config_path = get_absolute_path($login_config_file);
  rest_api_read_login_config($config_path);
}
else
{
  echo "USAGE:" . PHP_EOL;
  echo "php tenant_get.php LOGINFILE" . PHP_EOL;
  echo "EXAMPLE:" . PHP_EOL;
  echo "php tenant_get.php mylogin.json" . PHP_EOL;
  die();
}

// Get tenant JSON data
$tenant_id = rest_api_tenant_get_id();
$response = rest_api_get_expand("/tenant/{$tenant_id}");

// Print tenant data (unparsed string data)
echo $response . PHP_EOL;

// It is considered best practice to not close the <?php tag
// in a PHP-only file.

4.6. PUT (Update) Tenant Info

The following example shows how to update an entity object.

The code uses a PUT request to update the website key of the current tenant. GET is used to fetch the value of the website key.

<?php
/*
File: tenant_update.php

This example uses a PUT request to update the "website" key
of the current tenant.

Usage:

    php tenant_update.php LOGINFILE

Example:

    php tenant_update.php mylogin.json
*/

require_once __DIR__ . "/../../tools/lib/rest_api_lib.php";

// Helper function
function tenant_update_website($tenant_id, $website)
{
  // Server expects JSON encoding with JSON_UNESCAPED_SLASHES
  $json_data = json_encode($website, JSON_UNESCAPED_SLASHES);
  $response = rest_api_put(
    "/tenant/{$tenant_id}/keys/website",
    $json_data,
    "application/json");

  // Check response code
  if (202 !== rest_api_get_http_response_code())
  {
    echo "ERROR: COULD NOT UPDATE WEBSITE KEY\n";
    die();
  }
}

// Read config file with user credentials
if ($argc == 2)
{
  $login_config_file = $argv[1];
  $config_path = get_absolute_path($login_config_file);
  rest_api_read_login_config($config_path);
}
else
{
  echo "USAGE:" . PHP_EOL;
  echo "php tenant_update.php LOGINFILE" . PHP_EOL;
  echo "EXAMPLE:" . PHP_EOL;
  echo "php tenant_update.php mylogin.json" . PHP_EOL;
  die();
}

// Get tenant id
$tenant_id = rest_api_tenant_get_id();

// Get current tenant website address
$response = rest_api_get("/tenant/{$tenant_id}/keys/website");
$website_orig = json_decode($response);

echo "--------------------------------------" . PHP_EOL;
echo "TENANT UPDATE EXAMPLE" . PHP_EOL;
echo "--------------------------------------" . PHP_EOL;
echo "ORIGINAL WEBSITE KEY : {$website_orig}" . PHP_EOL;

// Update website
$website = "https://updatedwebsite.com";
tenant_update_website($tenant_id, $website);

// Show updated value
$response = rest_api_get("/tenant/{$tenant_id}/keys/website");
$website_updated = json_decode($response);
echo "UPDATED  WEBSITE KEY : {$website_updated}" . PHP_EOL;

// Restore original value
tenant_update_website($tenant_id, $website_orig);

// Show restored value
$response = rest_api_get("/tenant/{$tenant_id}/keys/website");
$website_restored = json_decode($response);
echo "RESTORED WEBSITE KEY : {$website_restored}" . PHP_EOL;

// It is considered best practice to not close the <?php tag
// in a PHP-only file.

4.7. Download Asset Files (image)

The following example shows how to download a system image file using a GET request. Image files are downloaded to the download subdirectory (modify the code to change this).

<?php
/*
File: image_get.php

This example uses a GET request to download sample image assets
as files.

Files will be saved in a folder named __download__ in the current
working directory (the directory on which the command is invoked).

Usage:

    php image_get.php LOGINFILE

Example:

    php image_get.php mylogin.json
*/

require_once __DIR__ . "/../../tools/lib/rest_api_lib.php";

function download_image($image_id, $dir_path)
{
  $response = rest_api_get("/image/{$image_id}/download");
  if (!is_dir($dir_path))
  {
    mkdir($dir_path);
  }
  $image_path = $dir_path . "{$image_id}.png";
  $file = fopen($image_path, "wb");
  if ($file)
  {
    fwrite($file, $response);
    fclose($file);
  }
}

// Read config file with user credentials
if ($argc == 2)
{
  $login_config_file = $argv[1];
  $config_path = get_absolute_path($login_config_file);
  rest_api_read_login_config($config_path);
}
else
{
  echo "USAGE:" . PHP_EOL;
  echo "php image_get.php LOGINFILE" . PHP_EOL;
  echo "EXAMPLE:" . PHP_EOL;
  echo "php image_get.php mylogin.json" . PHP_EOL;
  die();
}

// Download sample images
$dir_path = getcwd() . "/download/";
download_image("modem-mkr1000", $dir_path);
download_image("modem-mkr-gsm-1400", $dir_path);
download_image("modem-mkr-nb-1500", $dir_path);
download_image("microcontroller-atmega328p", $dir_path);
download_image("microcontroller-atmega2560", $dir_path);
download_image("microcontroller-nRF52840", $dir_path);

echo "IMAGE FILES DOWNLOADED" . PHP_EOL;

// It is considered best practice to not close the <?php tag
// in a PHP-only file.

Note the difference between downloading an asset file and obtaining information about the asset.

To download asset data, the download route is used; the response contains a binary object with file data for the asset with the image id “microcontroller-atmega328p”:

$response = rest_api_get("/image/microcontroller-atmega328p/download");

To download asset information, the base version of the route is used; the response contains JSON data:

$response = rest_api_get("/image/microcontroller-atmega328p");

The routes for assets that can be downloaded in this way are:

/image/{name}
/firmware_core/{name}
/tenant/{id}/firmware_appl/{name}

Assets have a string id (name), while entities have a numeric id.

Invoke the script to download files and list files in the download directory (created by the script):

4.8. GET Permissions (auth)

The RIoT Secure Platform has an advanced permission system. As a user of the REST API, when supplying authentication credentials, certain permissions will apply.

To find the permissions of the current user the /auth route is used.

Here is a code example that lists the current permissions:

<?php
/*
File: auth_permissions.php

This example uses a GET request to obtain info about permissions
for the current user.

Returned JSON data is parsed and printed.

Usage:

    php auth_permissions.php LOGINFILE

Example:

    php auth_permissions.php mylogin.json
*/

require_once __DIR__ . "/../../tools/lib/rest_api_lib.php";

// Read config file with user credentials
if ($argc == 2)
{
  $login_config_file = $argv[1];
  $config_path = get_absolute_path($login_config_file);
  rest_api_read_login_config($config_path);
}
else
{
  echo "USAGE:" . PHP_EOL;
  echo "php auth_permissions.php LOGINFILE" . PHP_EOL;
  echo "EXAMPLE:" . PHP_EOL;
  echo "php auth_permissions.php mylogin.json" . PHP_EOL;
  die();
}

// Get user info
$response_json = rest_api_get("/auth");
$user_info = json_decode($response_json);
$permissions = $user_info->permissions;

// List permissions
echo "AVAILABLE PERMISSIONS:\n";
echo "(C = Create, R = Read, U = Update, D = Delete, O = Options)\n";
foreach ($permissions as $route => $array)
{
  echo $route . " : ";
  foreach ($array as $permission)
  {
    echo $permission . " ";
  }
  echo "\n";
}

// It is considered best practice to not close the <?php tag
// in a PHP-only file.

Example output: