Page tree

cloudAPI.raml


Using the API requires an additional license called "Admin Package"


The goal of the API

This API will allow interactions with the cloud from external software, using only HTTP methods, HTTP error codes and JSON (JavaScript Object Notation).

About the API

The API follows the REST (Representational State Transfer) architectural style.

The API only uses the following HTTP methods:

  • GET

  • POST

  • PUT
  • DELETE

This is in order to be compatible with security restrictions that some of our users enforce.

Permissions

 Most API calls are available for cloud admins only. 

Calls which are available for project admins:

  • Get users (project users)
  • Add a new user (to the project)
  • Delete a user (unassigned from the project)



Calls which are available for users and project admins:


  • Get device (project device)
  • reservations new device (from the project devices group)
  • release device (from its current user)


  • Get applications (project applications)
  • Add a new application (to the project)
  • Delete an application (from the cloud)
  • Install \ Uninstall an application (from the cloud)


Rest API usage for project admins and users:

Project admins and users are allowed to access only users and applications which belong to the project they are currently signed in to.

In order to authenticate with a project, add a "ProjectName" header which will contain the name of the project.


Good to know

The API can be used with any language/tool that can communicate using HTTP.

Get more information about the actions we support in:

Calling the API

We are going to use a server named "my.cloud.server", Using the same port as the normal server GUI.


JUnit get projects Example
package cloud_api;

import java.io.*;
import java.net.*;
import java.nio.charset.StandardCharsets;

import org.apache.commons.codec.binary.Base64;
import org.junit.*;
 
/**
 * This example has 3 test methods:
 * 1) Get all cloud users.
 * 2) Add new cloud user.
 * 3) Delete a cloud user.
 */
public class TestCloudAPI {
    private static final String USERS_URL = "/users";
    private static final String NEW_USER_URL = USERS_URL+"/new";
    private static final String DELETE_USER_URL = USERS_URL+"/USER_ID/delete";
     
    //private String webPage= "http:/my.cloud.server/my/api/v1";
    private String host = "my.cloud.server";    // <== udpate your server here
    private String port = "80";                 // <== update to relevant port
    private String webPage= "http://" + host + ":" + port + "/api/v1";
    private String authStringEnc;
    private String getWhat;
 
    @Before
    public void setup() {
        String name = "admin";                    // <== update the log in name
        String password = "va1idPassword";        // <== update log in password
         
        String authString = name + ":" + password;
        byte[] authEncBytes = Base64.encodeBase64(authString.getBytes());
        authStringEnc = new String(authEncBytes);
    }
 
    @Test
    public void testGetUsers() throws IOException {
        getWhat = USERS_URL;
        doGet(USERS_URL);
    }
 
    @Test
    public void testPostNewUser() throws IOException {
        getWhat = NEW_USER_URL;
        String charset = StandardCharsets.UTF_8.name();
        
        String query = String.format("username=%s&firstName=%s&lastName=%s&email=%s&role=%s",
                URLEncoder.encode("test", charset), //user name (log in name)
                URLEncoder.encode("test", charset), //first name
                URLEncoder.encode("test", charset), //last name
                URLEncoder.encode("test@experitest.com", charset), //email
                URLEncoder.encode("User", charset));//role (one of the following: Admin/ProjectAdmin/User)

 
        doPost(USERS_URL+"/new", query);
    }
    
    @Test
    public void testDeleteUser() throws IOException {
        getWhat = DELETE_USER_URL;
        getWhat = getWhat.replace("USER_ID", "7");
        String query = ""; //no parameters
        doPost(getWhat, query);
    }

 
    /**
     * @param entity can be "/users" / "/projects" / "/devices" etc
     */
    private String doGet(String entity) throws IOException {
        URL url = new URL(webPage+entity);
        URLConnection urlConnection = url.openConnection();
        urlConnection.setRequestProperty("Authorization", "Basic " + authStringEnc);
        InputStream is = urlConnection.getInputStream();
        InputStreamReader isr = new InputStreamReader(is);
        int numCharsRead;
        char[] charArray = new char[1024];
        StringBuffer sb = new StringBuffer();
        while ((numCharsRead = isr.read(charArray)) > 0) {
            sb.append(charArray, 0, numCharsRead);
        }
        String result = sb.toString();
        printGet(url, (HttpURLConnection) urlConnection, result);
        if (((HttpURLConnection)urlConnection).getResponseCode() < 300) {
            return result;
        } else {
            throw new RuntimeException(result);
        }
    }
 
    /**
     * @param entity can be "/users" / "/projects" / "/devices" etc
     * String query = String.format("param1=%s&param2=%s", URLEncoder.encode(param1, charset), URLEncoder.encode(param2, charset));
     */
    private String doPost(String entity , String query) throws IOException {
        URL url = new URL(webPage+entity);
        URLConnection urlConnection = url.openConnection();
        urlConnection.setDoOutput(true);
        urlConnection.setRequestProperty("Accept", "application/json");
        urlConnection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded;charset=" + StandardCharsets.UTF_8.name());
        urlConnection.setRequestProperty("Authorization", "Basic " + authStringEnc);
 
        OutputStream output = urlConnection.getOutputStream();
        output.write(query.getBytes(StandardCharsets.UTF_8.name()));
         
        HttpURLConnection httpURLConnection = (HttpURLConnection) urlConnection;
        
        printPost(url, httpURLConnection);

        InputStream stream = null;
        
        if (httpURLConnection.getResponseCode() >= 400) {
            stream = httpURLConnection.getErrorStream();
            
        } else {
            stream = httpURLConnection.getInputStream();        
        }
        
        BufferedReader in = new BufferedReader(new InputStreamReader(stream));
        String inputLine;
        StringBuffer responseBuffer = new StringBuffer();

        while ((inputLine = in.readLine()) != null) {
            responseBuffer.append(inputLine);
        }
        in.close();
        
        //print result
        System.out.println(responseBuffer.toString());
        if (httpURLConnection.getResponseCode() < 300) {
            return responseBuffer.toString();
        } else {
            throw new RuntimeException(responseBuffer.toString());
        }
         
    }

    private void printPost(URL url, HttpURLConnection httpURLConnection) throws IOException {
        int responseCode = httpURLConnection.getResponseCode();
        System.out.println("\nSending 'POST' request to URL : " + url);
        System.out.println("Response Code : " + responseCode);
    }
 
    private void printGet(URL url, HttpURLConnection httpURLConnection, String result) throws IOException {
        int responseCode = httpURLConnection.getResponseCode();
        System.out.println("\nSending 'GET' request to URL : " + url);
        System.out.println("Response Code : " + responseCode);
        System.out.println(result);
    }
}


Chrome rest tool example:

new user frm cURL
curl -H "Authorization: Basic YWRtaW46RXhwZXJpdGVzdDIwMTI=" -X POST -F username=test -F firstName=test -F lastName=test -F email=test@experitest.com -F role=User http:/my.cloud.server/my/api/v1/users/new

Support API to a secured cloud with a self-signed certificate

In order to sent API to the secured cloud with self-signed certificate must add the following code.

Secured self-signed code extention
static {
    System.getProperties().setProperty("javax.net.ssl.trustStore","/* Path of the trust store */");
    System.getProperties().setProperty("javax.net.ssl.trustStorePassword","/* Password */");
}
  


 Steps for creating a new project, with users and devices, that use tokens:

  1. get available projects

  2. create a new project

  3. get all users

  4. create a new user

  5. assign a user to a project

  6. get available device groups

  7. assign a device group to the project

  8. set project’s token mode

  9. amend tokens

Steps for deleting the above project:

  1. delete users (that are in the project)
  2. delete the project.



  • No labels