Make a request with the appropriate method (POST/PUT) to the
designated API endpoint.
Include the necessary parameters as specified in the API
documentation.

Upon successful update, you should receive a response with code
200 and a corresponding message.

Q: What are the key features introduced in the V1.9.4 release
of BXAMGR?

A: The V1.9.4 release of BXAMGR includes various enhancements
such as:

Added connection property compatibility explanations.
Introduction of unique identifier features for GET APIs related
to device status and connections.

Definitions of zone-related APIs and compression mode support
parameters.
Addition of APIs for user favorites and active connection
summaries.

Updates on REST API version to v1.1 with support for zones and
compression modes.

“`

View Fullscreen

APPLICATION PROGRAM INTERFACE MANUAL
BXAMGR
BOXILLA REST API V1.9.4 MANUAL
24/7 TECHNICAL SUPPORT AT 1.877.877.2269 OR VISIT BLACKBOX.COM
HTTP/1.1 200 OK Accept: application/json; Content-Type: application/json; Accept-version: v1 Body: {
“code”: “200”, “message”: “Successfully updated REST username.” }

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
Master Document Revision History

Date Jan. 6th, 2020
Jan. 17th, 2020 Jan. 17th, 2020 Feb.17th, 2020
Mar.27th, 2020
May.5th, 2020 Jun.19th, 2020

Version 0.1
0.2 1.0 1.1
1.2
1.3 1.4

Description
Initial draft derived from the original northbound REST API document ENG0007-078, with the following updates:
· Added description of request parameter usage in JSON format for each API
· Removed all future features including templated-related and connection-group-related operations
· Removed all descriptions of appliance southbound REST API (user logout, launch/break active connections)
· Updated context based on the consolidated review comments
Update context based on the second group of consolidated review comments.
Moving to approved.
Parameter consistency update:
· replacing character “-” with “_” in API request · updating valid values for several parameters · ensuring consistency over various API types
(GET/POST/PUT/DELETE) Error case and response context update.
Added connection property compatibility explanation for usb_rediretion of viaTx connections and host for VMPool connections. Error case and response context update. Added description of unique identifier features for GET APIs for device status and connections. Removed description related to SSL certificate installation.
Added definition of GET API for active connection summary. URL correction of the API for editing connection properties. Response message update for user login API for active directory and nonactive-directory users.
Added definitions of zone-related APIs Added compression mode support parameters in connection APIs Added APIs for user favorites Updated REST API version from v1.0 to v1.1, representing support for zone and compression mode

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Jun.2nd, 2021

1.5

Mar. 7, 2022

1.6

Mar. 30, 2022

1.7

Nov. 28, 2022 Feb. 17, 2023

1.8 1.9.0

September 11th, 2023
Oct. 20th 2023
Nov. 17th 2023

1.9.1
1.9.2 1.9.3

Dec. 18th 2023

1.9.4

Added appendix section of recommended northbound REST API operation work-flow sequence
Added definitions for Remote App-oriented operations.
Updated Northbound REST API URI Format, added new root element into API hierarchy definition.
Updated POST APIs, added upload private key API.
Added definitions for Time-oriented operations.
Updated Northbound REST API URI Format, added new root element into API hierarchy definition.
Updated GET APIs, added time API.
Added APIs for retrieving Boxilla backup files
Extended Terminate KVM Active Connection and KVM User Logout APIs to include new optional parameter “splash_screen”: “Yes” | “No”. Renamed the TX settings parameter “DVI Optimised” to “DVI/DP Optimised” as to align with Boxilla GUI. Added new APIs for getting preset details and launching preset.
Updated preset APIs to introduce username for preset list and details requests.
Added “view_only” property for active connection summary response message.

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
Table of Contents
Table of Contents…………………………………………………………………………………………………………………… 4 List of Figures ………………………………………………………………………………………………………………………… 8 List of Tables …………………………………………………………………………………………………………………………. 9 Glossary of REST-related Terms ……………………………………………………………………………………………….. 9 1 Introduction …………………………………………………………………………………………………………………. 10 2 Boxilla REST API for External Management Platform Integration ………………………………………… 11
2.1 General Procedures ……………………………………………………………………………………………….. 11 2.2 Northbound REST API URI Format ……………………………………………………………………………. 11
2.2.1 GET APIs ………………………………………………………………………………………………………… 12 2.2.2 POST APIs ………………………………………………………………………………………………………. 12 2.2.3 PUT APIs ………………………………………………………………………………………………………… 12 2.2.4 DELETE APIs…………………………………………………………………………………………………….13 2.3 REST API Header……………………………………………………………………………………………………..13 2.3.1 Request/Response Formatting …………………………………………………………………………. 13 2.3.2 Authentication/Authorization and Security…………………………………………………………13 2.3.3 API Versioning ………………………………………………………………………………………………… 14 2.4 Error Response Cases for all APIs………………………………………………………………………………14 2.4.1 Response – Error: Bad Request …………………………………………………………………………. 14 2.4.2 Response – Error: UnAuthorized ……………………………………………………………………….. 15 2.4.3 Response – Error: Not Found……………………………………………………………………………..15 2.5 APIs for REST User Related Operations………………………………………………………………………15 2.5.1 API for Editing REST Username …………………………………………………………………………. 16 2.5.2 API for Editing REST Password ………………………………………………………………………….. 17 2.6 APIs for Versioning …………………………………………………………………………………………………. 19 2.6.1 Request – Uri ………………………………………………………………………………………………….. 19 2.6.2 Request Params……………………………………………………………………………………………. 19 2.6.3 Response – Success…………………………………………………………………………………………..19 2.7 APIs for Time-oriented Operations …………………………………………………………………………… 19 2.7.1 Request – Uri ………………………………………………………………………………………………….. 19 2.7.2 Request Params……………………………………………………………………………………………. 20

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
2.7.3 Response – Success…………………………………………………………………………………………..20 2.8 APIs for User-oriented Operations……………………………………………………………………………. 20
2.8.1 API for Creating KVM Users ……………………………………………………………………………… 20 2.8.2 API for Editing KVM Users ………………………………………………………………………………… 23 2.8.3 API for Deleting All KVM Users …………………………………………………………………………. 25 2.8.4 API for Deleting Specific KVM Users ………………………………………………………………….. 26 2.8.5 API for Getting KVM Users ……………………………………………………………………………….. 28 2.8.6 API for Editing Associations between KVM Users and Connections………………………..30 2.8.7 API for KVM User Login to Receivers …………………………………………………………………. 31 2.8.8 API for KVM User Logout from Specific Receivers ……………………………………………….. 33 2.8.9 API for Editing User Favorites as Global or to Zones ……………………………………………. 36 2.9 APIs for Device-oriented Operations ………………………………………………………………………… 39 2.9.1 API for Getting KVM Appliances………………………………………………………………………… 39 2.9.2 API for Getting KVM Appliance Properties …………………………………………………………. 41 2.9.3 API for Setting KVM Receiver Properties ……………………………………………………………. 43 2.9.4 API for Setting KVM Transmitter Properties ……………………………………………………….. 46 2.9.5 API for Setting KVM Receiver Zone assignment ………………………………………………….. 49 2.9.6 API for Getting KVM Appliance Status ……………………………………………………………….. 51 2.9.7 API for Rebooting all KVM Appliances ……………………………………………………………….. 53 2.9.8 API for Rebooting selected KVM Appliances ………………………………………………………. 54 2.10 APIs for Connection-oriented Operations …………………………………………………………………. 55 2.10.1 API for Creating KVM Connections ……………………………………………………………………. 57 2.10.2 API for Editing KVM Connection Profiles/Properties ……………………………………………. 61 2.10.3 API for Deleting all KVM Connections…………………………………………………………………64 2.10.4 API for Deleting Specific KVM Connections ………………………………………………………… 65 2.10.5 API for Getting KVM Connection Status………………………………………………………………67 2.10.6 API for Launching KVM Active Connections…………………………………………………………70 2.10.7 API for Terminating KVM Active Connections …………………………………………………….. 72 2.10.8 API for Getting All KVM Active Connection Status………………………………………………..75 2.10.9 API for Getting KVM Active Connection Status Summary …………………………………….. 76 2.10.10 API for getting connection preset list …………………………………………………………….. 78

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
2.10.11 API for getting preset details ………………………………………………………………………… 79 2.10.12 API for getting preset status summary …………………………………………………………… 81 2.10.13 API for launching preset………………………………………………………………………………..83 2.11 APIs for Zone-oriented Operations …………………………………………………………………………… 85 2.11.1 API for Getting Overview of all Zone Information ……………………………………………….. 85 2.11.2 API for Getting Information of Individual Zone …………………………………………………… 86 2.11.3 API for Creating Zones……………………………………………………………………………………… 88 2.11.4 API for Editing Name/Description of Individual Zone …………………………………………… 90 2.11.5 API for Editing Associations between Zones and KVM Receivers……………………………92 2.11.6 API for Editing Associations between Zones and KVM Connections ………………………. 93 2.11.7 API for Deleting All Zones………………………………………………………………………………….95 2.11.8 API for Deleting Specific Zones …………………………………………………………………………. 95 2.12 APIs for Remote App-oriented operations ………………………………………………………………… 97 2.12.1 API for Uploading Remote App Headless CLI Private Key ……………………………………… 97 2.13 APIs for retrieving backup files ………………………………………………………………………………… 99 2.13.1 API for retrieving list of backup files ………………………………………………………………….. 99 2.13.2 API for downloading backup files from Boxilla ……………………………………………………. 99 3 REST Specific HTTP Error Status Codes …………………………………………………………………………… 101 4 Appendix ……………………………………………………………………………………………………………………. 102 4.1 Appliance Property (Settings) Capabilities based on Device Class and Firmware Version.102 4.2 API Requests involving Multiple Operations…………………………………………………………….. 103 4.3 Naming Validation Rules ……………………………………………………………………………………….. 104 4.3.1 Rules for Valid Name of KVM Users/Devices/Connections …………………………………. 104 4.3.2 Rules for Valid Password…………………………………………………………………………………105 4.3.3 Rules for Valid Zone Name………………………………………………………………………………105 4.4 Recommended API Operation Work-flow Sequence to support: KVM User Login, Connection Launch, Connection Terminate and KVU User Logout…………………………………………………………..105 4.5 Recommended API Operation work-flow sequence to support preset launch………………114 4.5.1 Typical Work-flow for Launching a Preset From NBR …………………………………………. 114 4.5.2 Retrieve Preset Information……………………………………………………………………………. 114 4.5.3 Launch Preset………………………………………………………………………………………………..115

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager
ENG-007-100100

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager
ENG-007-100100
List of Figures
Fig. 1 Sequence of KVM user login request and status check (step 1 & 2)…………………………………..108 Fig. 2 Sequence of launching KVM active connection and status check (step 3 & 4)…………………….110 Fig. 3 Sequence of terminating KVM active connection and status check (step 5 & 6) ………………… 111 Fig. 4 Sequence of KVM user logout and status check (step 7 & 8)……………………………………………. 113 Figure 5 recommended workflow for retrieving preset information …………………………………………. 114 Figure 6 recommended workflow for launching preset (200 success) ……………………………………….. 115 Figure 7 recommended workflow for launching preset (200 partial success) …………………………….. 116 Figure 8 recommended workflow for re-launch preset (timeout) …………………………………………….. 117 Figure 9 recommended workflow for re-launch preset (400 / 401 error)……………………………………118

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
List of Tables
No table of figures entries found.

Glossary of REST-related Terms

Term

Description

REST

Representational State Transfer. An architectural style that uses HTTP as the transport protocol for the message requests and responses.

API

Application Programming Interface. Enables different systems to interact with each other programmatically.

URI

Uniform Resource Identifier. A string containing an identifier (usually a name or an address) which refers to a resource in the web.

GET A REST operation to retrieve a resource.

POST A REST operation to create a resource.

PUT A REST operation to update or create within an existing resource.

DELETE A REST operation to remove a resource.

JSON

JavaScript Object Notation. A lightweight syntax containing objects and arrays, usually used (instead of XML) to return information from a REST API.

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager
ENG-007-100100
1 Introduction
Blackbox hardware devices are managed on Boxilla via web services that provide functionalities of creating, removing, updating and validating KVM devices, connections and user profiles. The corresponding functionalities are required as independent components which can be integrated into and accessed potentially by third-party management platforms used by customers for Blackbox device management, other than accessing devices directly from Boxilla.
This document provides the definition of Boxilla northbound REST API that acts as the management interface integrated with any third-party management tools. Requirements on the REST API functionalities are listed but not limited as follows:
· Add support to create/edit/delete profiles of KVM users and get information of individual/multiple users
· Add support to log KVM users in to or out from KVM receivers · Add support to update API authentication credentials (username/password) · Add support to get list of transmitters/receivers, properties and status · Add support to reboot individual/multiple devices · Add support to create/delete KVM connections, get connection information and edit
connection properties · Add support to retrieve Boxilla backup files · Add support to launch connection preset
The northbound REST API is designed as one of the new features for Boxilla 3.5. It is NOT supported by Boxilla with version older than 3.5.

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
2 Boxilla REST API for External Management Platform Integration
2.1 General Procedures
Version 1.1 of the northbound REST APIs listed in this document provides administrator level of operations to Boxilla system and the associated resources. For this reason, they are disabled and cannot be accessed by external management platforms by default. Configuration of enabling northbound REST APIs is managed by Boxilla via its web interface. Potential REST API users should enable the northbound REST APIs (and only enable them when required) before using them, otherwise all requests via the APIs would fail and with no response.
2.2 Northbound REST API URI Format
The URI of each northbound REST API designed in this document is formatted as follows:
scheme “://” authority “/” path [ “?” query ] [ “#” fragment ] The path field within the format is defined using the following hierarchy rules:
· users o kvm o system
· devices o kvm o switches o dkm
· peripherals o usb-extenders
· connections o kvm o dkm o presets
· zones · remoteapp · time · backups

As the northbound REST API is designed for the majority of REST functionalities for Boxilla in general, the authority field within the URI is defined as bxa-api.
The following sections list the URLs of all the northbound REST APIs accessed using the GET, POST, PUT and DELETE verbs, respectively.

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.2.1 GET APIs

Scope

URL

Users Devices
Connections
Zones Versioning
Time Backups

bxa-api/users/kvm bxa-api/devices/kvm bxa-api/devices/kvm/properties bxa-api/devices/kvm/status bxa-api/connections/kvm bxa-api/connections/kvm/active bxa-api/connections/kvm/active/summary bxa-api/connections/presets bxa-api/connections/presets/details bxa-api/connections/presets/active/summary bxa-api/zones bxa-api/zones/all bxa-api/version bxa-api/time bxa-api/backups/list bxa-api/backups/download

2.2.2 POST APIs

Scope

URL

Users
Devices Connections
Zones Remote App

bxa-api/users/kvm bxa-api/users/kvm/login bxa-api/users/kvm/logout bxa-api/users/kvm/favs bxa-api/devices/kvm/reboot bxa-api/devices/kvm/reboot-all bxa-api/devices/kvm/rx/zones bxa-api/connections/kvm bxa-api/connections/kvm/active bxa-api/connections/presets/activate bxa-api/zones bxa-api/zones/devices/kvm/rx bxa-api/zones/connections/kvm bxa-api/remoteapp/cli_data_key

2.2.3 PUT APIs

Scope

URL

Users Devices Connections

bxa-api/users/kvm bxa-api/users/kvm/connections bxa-api/devices/kvm/properties/rx bxa-api/devices/kvm/properties/tx bxa-api/connections/kvm

API version

v1.1

API version

v1.1

API version

v1.1

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Zones

bxa-api/zones

REST

bxa-api/users/rest/username

Authentication bxa-api/users/rest/password

2.2.4 DELETE APIs

Scope

URL

Users Connections
Zones

bxa-api/users/kvm
bxa-api/users/kvm/all bxa-api/connections/kvm bxa-api/connections/kvm/all bxa-api/connections/kvm/active bxa-api/zones bxa-api/zones/all

API version

v1.1

2.3 REST API Header
The header of each REST API defined in this document contains universal information that applies to all APIs, validated by Boxilla. A standard example of the header of a Boxilla northbound REST API in this document is defined as follows:
Accept: application/json
Content-Type: application/json
Authorization: Basic bG9sOnNlY3VyZQ==
Accept-version: v1.1
Each field of the header is discussed in the following sections.
2.3.1 Request/Response Formatting The “Accept: application/json” and “Content-Type: application/json” fields in each REST API request header indicate that the body of API request and response is in JSON format.
If these fields are not provided in the API request header, a standard HTTP-302 response would be returned by Boxilla.
2.3.2 Authentication/Authorization and Security The Northbound REST APIs listed in this document use HTTPs by default, configurable on port 443.
The “Authorization: Basic ……” field in the header of each API request indicates that all requests/responses of the REST APIs in this document use basic authentication method for authentication/authorization. A universal REST API user with a username-password credential pair is designed for operations over REST APIs for all KVM devices and connections, independent from the

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
associated KVM user accounts. This credential pair is deployed in Boxilla with uniqueness, encoded with Base64 algorithm and included after the “Basic” context in any API request header.
The default REST API authentication/authorization credential pair used in Boxilla is as follows:
· Username: REST_BbAdminUser · Password: Boxill@2020
As mentioned in section 2.1, the northbound REST APIs are with administrator level access of Boxilla system and resources, which is guaranteed by using this default REST credential pair. New credential pairs potentially added in future design can be used to change the access level.
2.3.3 API Versioning Versioning is handled in the customized REST API request/response header to preserve URIs between versions using the “Accept-version” field.
The default version number to be used is v1.1. REST APIs defined in the previous versions (v1) are still supported within this version.
2.4 Error Response Cases for all APIs
The success/error response of each northbound REST API in this document follows the HTTP-statuscode style of response, using status code to represent various cases together with details of the response. The API response header includes the version of API being used via the request and the response body contains the detailed description of the response status in a “message” field in JSON.
The following error response cases apply to all the REST APIs defined in this document:
2.4.1 Response – Error: Bad Request This error response indicates any non-specific error that might be caused by internal errors within the API, with the following format:
HTTP/1.1 400 Bad Request Accept: application/json; Content-Type: application/json; Accept-version: v1 Body:
{ “code”: “400”, “message”: “[Error details].” } The detailed error message varies depending on the actual error case related. The individual error case would be discussed in the definition of each REST API, respectively.

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
2.4.2 Response – Error: UnAuthorized This error response indicates that the operation related to the API request is not authorized on Boxilla, usually caused by an invalid authentication credential.
HTTP/1.1 401 UnAuthorized
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “401”, “message”: “Operation is not authorized.” }
2.4.3 Response – Error: Not Found This error response indicates that the API request URL does not exist. The error case is handled with a HTML-format error response. Version 1 of northbound REST API does not customize this error response in JSON.
HTTP/1.1 404 Not Found
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
<html lang=”en”> <head> <meta charset=”utf-8″ /> <title>Action Controller: Exception caught</title> </head> <body> <center><br><br><img src=”/assets/bbb_logo.png”><br><br> <h2>404: Resource not found.</h2><br><br> <h3>Please return and try again</h3> <a href=”/”><button class=”btn btn-default” type=”button”>Dashboard</button></a><br><br> <small><i>Routing Error</i></small> </body> </html>
2.5 APIs for REST User Related Operations
The APIs for REST user management include the following functionalities:
· Change username/password of the REST user account credential

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

The associated definition of each API is listed as follows:

2.5.1 API for Editing REST Username

2.5.1.1 Request – Uri

Uri

bxa-api/users/rest/username

Method

PUT

2.5.1.2 Request – Params Requirement Name

Mandatory

username new_username

Type
String String

Description
Current username credential of the REST API user. Maximum length 64. New username credential of the REST API user to change to. Maximum length 64.

2.5.1.3 Request Body JSON Format
{ “username”: “[username]”, “new_username”: “[new_username]” }

2.5.1.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Successfully updated REST username.” }
2.5.1.5 Response Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.5.1.6 Response Error: REST Username Credential already Exists This error indicates that the new REST username credential to be updated to (specified by the “new_username” parameter) already exists.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Cannot update REST username to [new_username], [new_username] already exists.” }

2.5.1.7 Response Error: Northbound REST API is not enabled for the REST User This error indicates that northbound REST API is disabled for the specified REST user specified by the “username” parameter.

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Editing REST authentication credentials is forbidden for user [username]. REST API is not accessible for this user.” }

2.5.2 API for Editing REST Password

2.5.2.1 Request – Uri

Uri

bxa-api/users/rest/password

Method

PUT

2.5.2.2 Request – Params Requirement Name

Mandatory

username new_password

Type
String String

Description
Current username credential of the REST API user. Maximum length 64. New password credential of the REST API user to change to. Maximum length 32.

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
2.5.2.3 Request Body JSON Format { “username”: “[username]”, “new_password”: “[new_password]” }
2.5.2.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Successfully updated REST user password.” }
2.5.2.5 Response Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:
· Parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· The username credential provided in the parameters does not match the existing valid credential. The associated error message in the response body is as follows: “message”: “REST username [username] does not exist.”
2.5.2.6 Response Error: Northbound REST API is not enabled for the REST User This error indicates that northbound REST API is disabled for the specified REST user specified by the “username” parameter.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Editing REST authentication credentials is forbidden for user [username]. REST API is not accessible for this user.” }

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.6 APIs for Versioning

This API is to get versioning information related to Boxilla components, including information of the following items each with fixed format:

· Boxilla software version o Format is [major_version].[minor_version].[patch].[build_number], e.g. 3.4.1.5120
· Northbound REST API version: fixed as “v1” for API version 1 · Boxilla model number: fixed as “BXAMGR” · Boxilla serial number: e.g. AEBB19B00022

2.6.1 Request – Uri

Uri

bxa-api/version

Method

GET

2.6.2 Request Params This API does not require any parameters within the request body.

2.6.3 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: { “software-version”: “[boxilla software version]”, “api_version”: “v1”, “model_number”: “BXAMGR”, “serial_number”: “[boxilla serial number]” } }

2.7 APIs for Time-oriented Operations

This API is to retrieve current Boxilla time, including UTC time and Local time. All values are returned in epoch format.

· local_time Boxilla local time (timezone aware) · utc_time Boxilla UTC time

2.7.1 Request – Uri

Uri

bxa-api/time

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Method

GET

2.7.2 Request Params This API does not require any parameters within the request body.

2.7.3 Response – Success
HTTP/1.1 200 OK
Content-Type: application/json;
Accept-version: v1.1
Body:
{ “code”: “200”, “message”: { “local_time”: “1648628865”, “utc_time”: “1648628865” }
}

2.8 APIs for User-oriented Operations
The APIs for Boxilla user operations include functionalities as follows:
· Creating new KVM users · Editing existing KVM user profiles · Deleting existing KVM users · Getting KVM users (individual/all) · Editing associations between KVM users and connections · Logging users in to KVM receivers · Logging users out from KVM receivers
The associated definition of each API is listed as follows:
2.8.1 API for Creating KVM Users
This API is to create a new KVM user in Boxilla using a valid credential set (username + password) from the API input parameters, together with the property set associated to the user. For each API request, one of the following categories of user property sets is defined with the relevant parameters passed in apart from the user credential (username/password):
· Unique property: user is created with a unique set of properties defined with the API request parameters. In this case the request of the API should contain the following parameters for the user property:

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

o privilege: identifying the privilege of the user, valid values including “Administrator”, “PowerUser” or “GeneralUser”.
o auto_connect: identifying whether the auto-connection option of the user property is enabled, valid values including “Yes” or “No”.
o auto_connect_name: identifying the name of the auto-connection if the property is enabled.
o remote_access: identifying whether access of the user profile via the remote windows application is enabled, valid values include “Yes” or “No”.
Version 1 of northbound REST API does not support user-related operations with non-unique properties, including template-based and system properties.

The “Requirement” column in the parameter table represents whether each parameter is mandatory, conditional-mandatory or optional, depending on specific values of some parameters as follows:

· Mandatory: the parameter is required · Conditionally Optional: the parameter is optional depending on values of one or more other
parameters.

2.8.1.1 Request – Uri

Uri

bxa-api/users/kvm

Method

POST

2.8.1.2 Request – Params

Requirement

Name

Type Description

Mandatory
Conditionally Optional

username password privilege remote_access auto_connect auto_connect_name

String String String String String String

Username credential of KVM user. Maximum length 64.
Password credential of KVM user. Maximum length 32.
User privilege. Valid values are: “Administrator” | “PowerUser” | “User”. (Case sensitive) Enabled/disabled option for remote app access. Valid values are “Yes” or “No”. (Case sensitive) Enabled/disabled option for auto-connection. Valid values are “Yes” or “No”. (Case sensitive) Name of the auto-connection if enabled. Maximum length 64. Applicable when “auto_connect” is “Yes”.

2.8.1.3 Request Body JSON Format
{ “username”: “[username]”, “password”: “[password]”, “privilege”: “Administrator” | “PowerUser” | “User”, “remote_access”: “Yes” | “No”,

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“auto_connect”: “Yes” | “No”, “auto_connect_name”: “[auto_connect_name]”, // only add it when “auto_connect” is “Yes” }
2.8.1.4 Response – Success
HTTP/1.1 201 Created
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “201”, “message”: “Created user [username].” }
2.8.1.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:
· Username/password or other required property parameters are passed in as empty or invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· When “auto_connect” is enabled, the provided “auto_connect_name” parameter value is not the name of any existing KVM connections. The associated error message in the response body is as follows: “message”: “Invalid parameter: auto_connect_name [auto_connect_name] does not point to any existing KVM connections.”
· “auto_connect_name” parameter is provided when “auto_connect” is disabled. The associated error message in the response body is as follows: “message”: “Invalid parameter: auto_connect_name [auto_connect_name] cannot be set when auto_connect is disabled. ”
2.8.1.6 Response – Error: License-related Failure This error response indicates that the Boxilla license installed on the server is invalid, expired or limitation of the maximum number of users is reached.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”,

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“message”: “License limit reached.” }

2.8.1.7 Response – Error: User Already Exists This error response indicates that a KVM user record with the specified username already exists and
the API request is attempting to create a duplicate record.

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Duplicate name received.” }

2.8.2 API for Editing KVM Users This API is to edit the profile/properties of an existing KVM user. The request of the API should contain the user profile/property parameters to be updated.

2.8.2.1 Request – Uri

Uri

bxa-api/users/kvm

Method

PUT

2.8.2.2 Request – Params

Requirement

Name

Type Description

Mandatory
Optional Conditionally Optional

username password privilege remote_access auto_connect new_username auto_connect_name

String String String String String String String

Username credential of KVM user. Maximum length 64. Password credential of KVM user. Maximum length 32. User privilege. Valid values are: “Administrator” | “PowerUser” | “User”. (Case sensitive) Enabled/disabled option for remote app access. Valid values are “Yes” or “No”. (Case sensitive) Enabled/disabled option for auto-connection. Valid values are “Yes” or “No”. (Case sensitive) New username to be edited. Maximum length 64. Username is updated if provided. Name of the auto-connection if enabled. Maximum length 64.

2.8.2.3 Request Body JSON Format {

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
“username”: “[username]”, “password”: “[password]”, “privilege”: “Administrator” | “PowerUser” | “User”, “remote_access”: “Yes” | “No”, “auto_connect”: “Yes” | “No”, “auto_connect_name”: “[auto_connect_name]” // only add it when “auto_connect” is “Yes” “new_username”: “[new_username]” // Optional, username is updated if provided }
2.8.2.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Updated profile/properties for user [username].” }
2.8.2.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:
· Required parameters are passed in as empty or invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· One or more KVM users within the username list parameter do not exist. The associated error message in the response body is as follows: “message”: “User [username] does not exist.”
· When “auto_connect” is enabled, the provided “auto_connect_name” parameter value is not the name of any existing KVM connections. The associated error message in the response body is as follows: “message”: “Invalid parameter: auto_connect_name [auto_connect_name] does not point to any existing KVM connections.”
· “auto_connect_name” parameter is provided when “auto_connect” is disabled. The associated error message in the response body is as follows: “message”: “Invalid parameter: auto_connect_name [auto_connect_name] cannot be set when auto_connect is disabled. ”
2.8.2.6 Response Error: Changing Username to Name of Existing User This error response indicates that the new username to be changed to belongs to an existing user. The associated error message in the response body is as follows:

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Cannot update username to [new_username]. User [new_username] already exists.” }
2.8.2.7 Response Error: Attempting to Edit Properties of non-Unique Users This error response indicates that the specified user is with non-unique properties. Editing properties of the user would be prohibited by the northbound REST API and a HTTP 403 error response is returned. The associated error message in the response body is as follows:
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: ” Editing properties for non-unique user [username] is not supported.” }

2.8.3 API for Deleting All KVM Users

This API is to delete all the existing KVM users with unique properties in Boxilla.

2.8.3.1 Request – Uri

Uri

bxa-api/users/kvm/all

Method

DELETE

2.8.3.2 Request Params This API does not require any parameters within the request body. The version of API is included in the request header, as described in section 2.3.3.

2.8.3.3 Response – Success
HTTP/1.1 200 OK Accept: application/json; Content-Type: application/json; Accept-version: v1

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Body:
{ “code”: “200”, “message”: “Successfully deleted all users.” }
2.8.3.4 Response Error: User Logged on Receivers or in Active Connection This error response indicates that one or more users are actively logged in receivers or are in active connections. The associated error message in the response body is as follows:
HTTP/1.1 409 Conflict
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “409”, “message”: “Fail to delete user(s) [list of active users] because one or more users are logged on receivers or in active connections.” }

2.8.4 API for Deleting Specific KVM Users This API is to delete one or more KVM users with unique properties in Boxilla, specified by the request parameter which contains a list of existing usernames to be deleted.

2.8.4.1 Request – Uri

Uri

bxa-api/users/kvm

Method

DELETE

2.8.4.2 Request – Params Requirement Name

Mandatory

usernames

Type
String array

Description
List of names of the KVM users to be deleted. If array is empty with no usernames inside, the API request is successful but no user would be deleted.

2.8.4.3 Request Body JSON Format
{ “usernames”: [“[username_1]”, “[username_2]”, …] }

2.8.4.4 Response – Success
HTTP/1.1 200 OK Accept: application/json; Content-Type: application/json;

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
Accept-version: v1 Body:
{ “code”: “200”, “message”: “Successfully deleted user(s) [usernames].” }
2.8.4.5 Response Success with Empty Usernames Parameter
HTTP/1.1 204 No Content Accept: application/json; Content-Type: application/json; Accept-version: v1
2.8.4.6 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:
· Required parameters are passed in as empty (null parameter, not parameter as an empty array) or invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· “usernames” parameter is not an array (for example, an integer is given instead) or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter usernames: [usernames], expecting a String array.”
· One or more KVM users within the username list parameter do not exist. The associated error message in the response body is as follows: “message”: “The following user(s) do(es) not exist: [List of usernames do not exist]”
2.8.4.7 Response Error: Attempting to Delete Users with non-Unique Properties This error response indicates that one or more KVM users specified in the parameters are with nonunique properties. Deleting these users would be prohibited by the northbound REST API and a HTTP 403 error response is returned. Meanwhile all the other valid users specified in the parameters would still be successfully deleted.
The associated error message in the response body is as follows:
HTTP/1.1 403 Forbidden Accept: application/json; Content-Type: application/json; Accept-version: v1
Body:
{

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“code”: “403”, “message”: “The following users are with non-unique properties: [List of usernames].” }
2.8.4.8 Response Error: User Logged on Receivers or in Active Connection This error response indicates that one or more users are actively logged in receivers or are in active connections. The associated error message in the response body is as follows:
HTTP/1.1 409 Conflict
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “409”, “message”: “Fail to delete user(s) [list of active users] because one or more users are logged on receivers or in active connections.” }

2.8.5 API for Getting KVM Users This API is to obtain one or more KVM users on Boxilla, specified by the request parameter.

2.8.5.1 Request – Uri

Uri

bxa-api/users/kvm

Method

GET

2.8.5.2 Request Params

Requirement

Name

Optional
Note:

usernames

Type
String array

Description
List of names of the KVM users to get. If array is empty with no usernames inside, the API request is successful but no user would be returned in response body.

If no parameter is provided by the API request (parameter is null, not an empty array), the operation would be considered as getting all KVM users and the response is returned accordingly.

If the “usernames” parameter is an empty array, the API request is successful but no user is returned in the response (the “users” JSON array in response body is empty).

2.8.5.3 Request Body JSON Format
{ “usernames”: [“[username_1]”, “[username_2]”, …] // Optional, can be null or empty array }

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
2.8.5.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: { “users”: [
{ “username”: “[username]”, “privilege”: “Administrator” | “PowerUser” | “User”, “auto_connect”: “Yes” | “No”, “auto_connect_name”: “[auto_connect_name]”, // available if “auto_connect” is “Yes” “remote_access”: “Yes” | “No”, “connections”: [ {
“connection_name”: “[connection_name]” }, {….}, …. // if there are more connections ] }, {….}, // if there are more users …. ] } } In the “message”->”users” JSON array field in the response body, the following keys are mandatory (always be present) in each JSON element of the array:
· username · privilege · remote_access · auto_connect
The “auto_connection_name” key is conditionally optional based on the value of the “auto_connect” parameter. Meanwhile the value “connections” key depends on the associated connection list of the specified user.
2.8.5.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”
· “usernames” parameter is not an array (for example, an integer is given instead) or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter usernames: [usernames], expecting a String array.”
· One or more KVM users within the username list parameter do not exist. The associated error message in the response body is as follows: “message”: “The following user(s) do(es) not exist: [List of usernames do not exist]”

2.8.6 API for Editing Associations between KVM Users and Connections This API is to edit the association between a KVM user and a list of KVM connections, each of which is either attached to or detached from the KVM user.

2.8.6.1 Request – Uri

Uri

bxa-api/users/kvm/connections

Method

PUT

2.8.6.2 Request – Params

Requirement Name

Type Description

username

String

Name of the KVM user that owns the list of KVM connections.

Mandatory

connection_names

String array

List of names of the KVM connections to be associated to the KVM user. Can be an empty array.

The operation of this API depends on the value of the connection_names parameter as follows:

· If the parameter includes one or more valid connection names, all existing associations of KVM connections to the specified KVM user are removed and a new user-connection association is created for each KVM connection included in the parameter to the KVM user.
· If the parameter is an empty array, all existing associations of KVM connections to the specified KVM user are removed.

2.8.6.3 Request Body JSON Format
{ “username”: “[username]”, “connection_names”: [“[connection_1]”, “[connection_2]”, …] //Mandatory, can be empty array }

2.8.6.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Accept-version: v1
Body:
{ “code”: “200”, “message”: “Successfully updated connection associations for user [username].” }
2.8.6.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:

· Parameters are passed in as invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]. ”
· “connection_names” parameter value is not an array or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter connection_names: [connection_names], expecting a String array.”
· No KVM user exists with the specified username parameter in the request body. The associated error message in the response body is as follows: “message”: “User [username] does not exist.”
· No KVM connections exist with the specified connection name parameters in the request body. The associated error message in the response body is as follows: “message”: “The following connection(s) do(es) not exist: [connection_names].”
· The maximum limit of connections (22500) can be associated to a user has been reached. The associated error message in the response body is as follows: “message”: “User connection limit reached.”

2.8.7 API for KVM User Login to Receivers This API is to login a KVM user to a specific receiver or group of receivers, with a force-login option enabled or disabled. Enabling force-login would log out the alternative KVM user logged in currently, while disabling force-login results in a failure of the API request when another KVM user is logged in. The KVM user can be an active directory user whose record is not managed on Boxilla.

The force-login option is set as a parameter within the request body. Valid parameters are listed in the parameter table below.

2.8.7.1 Request – Uri

Uri

bxa-api/users/kvm/login

Method

POST

2.8.7.2 Request – Params Requirement Name Type

Description

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Mandatory

username password
rx_list

String
String String array

forced String

Username of the KVM user for logging in. Password of the KVM user for logging in.
The list of receiver names that the user logs in.
String parameter indicates login operation is a force-login or not. Valid values are “Yes” or “No”. Note: force-login would break existing active connections

2.8.7.3 Request Body JSON Format
{
“username”: “[username]”, “password”: “[password]”, “rx_list”: [“[receiver_1]”, “[receiver_2]”, ….], // Mandatory, API does nothing if empty array is given “forced”: “Yes” | “No” }

2.8.7.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “User [username] has successfully logged in to the target receivers.” }

2.8.7.5 Response – Error: Bad Request This error response may be caused by:

· Parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· One or more receivers included in the rx-list parameter are offline. The associated error message in the response body is as follows: “message”: “The following receiver(s) to log in is(are) offline: [List of offline receiver names]”
· The login functions on one or more receivers included in the rx-list parameter are malfunctional. The associated error message in the response body is as follows: “message”: ” “User login failed on the following receiver(s): [List of malfunctional receiver names]”
· The KVM user specified by the username parameter does not exist. This happens when the provided user is neither managed by Boxilla, nor active directory option is enabled. The associated error message in the response body is as follows:

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“message”: “User [username] does not exist. ”

2.8.7.6 Response – Error: UnAuthorized This error response may be caused by:

· The REST user credentials included in the request header are invalid, as described in section 2.4.2.
· The user is a local user created on Boxilla and the login password provided in request parameters is incorrect. The associated error message in the response body is as follows: “message”: “Operation is not authorized due to invalid login credentials.”
· The user is an active directory user managed by active directory server and the login credentials for it are incorrect. The associated error message in the response body is as follows: “message”: ” Operation is not authorized. Active directory user authentication failed on one or more target receivers. Please check the active directory server configuration on your Boxilla and make sure the credentials are correct.”

2.8.7.7 Response – Error: Logging in with Force-Login Disabled while Alternative User is Logged in
This error response indicates that another user is logged in to one or more receivers listed in the rxlist parameter, with the force-login option disabled. In this case the non-force-login operation from the API request would be rejected.

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Another user is logged in target receiver(s) [rx_list with user logged in].” }

2.8.8 API for KVM User Logout from Specific Receivers This API is to log out a KVM user from a specific receiver or group of receivers. Valid parameters are listed in the parameter table below.

2.8.8.1 Request – Uri

Uri

bxa-api/users/kvm/logout

Method

POST

2.8.8.2 Request – Params

Requirement Name

Type

Description

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Mandatory Optional

username rx_list

String String array

forced

String

splash_screen String

Username of the KVM user for logging out.
List of receiver names that the user logs out.
An Integer number indicating that the login operation is a force-logout or not. Valid values are “Yes” or “No”. Note: force-logout would break existing active connections String indicating if the splash screen should be displayed following User Logout. Valid values are “Yes” or “No”.

2.8.8.3 Request Body JSON Format
{ “username”: “[username]”, “rx_list”: [“[receiver_1]”, “[receiver-2]”, ….], // Mandatory, API does nothing if empty array is given “forced”: “Yes” | “No”, “splash_screen”: “Yes” | “No” }

2.8.8.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “User [username] has successfully logged out to the target receivers.” }

2.8.8.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API)
returned, which might include:

· Parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· One or more receivers included in the rx-list parameter do not exist. The associated error message in the response body is as follows: “message”: “The following receiver(s) do(es) not exist: [List of non-exist receiver names].”
· One or more receivers included in the rx-list parameter are offline. The associated error message in the response body is as follows: “message”: “The following receiver(s) to log out from is(are) offline: [List of offline receiver names]”

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
· The KVM user specified by the username parameter does not exist. This happens when the provided user is neither managed by Boxilla, nor active directory option is enabled. The associated error message in the response body is as follows: “message”: “User [username] does not exist. ”
· User logout operation fails on one or more receivers due to internal issues. The associated error message in the response body is as follows: “message”: “User logout failed on the following receiver(s): [List of receiver names where logout failed]. Other users are successfully logged out.”
2.8.8.6 Response – Error: Logging out not Supported by Receiver Firmware This error response indicates that the firmwares on one or more receivers do not support the associated user-logoff functionality required by this API.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Logout via northbound REST API is not supported by the following receiver(s): [List of receivers not supporting user logout].” }
2.8.8.7 Response – Error: Logging out with Force-Logout Disabled while Connections associated to User are Active
This error response indicates that there are active connections associated to the user exist on one or more receivers the user attempts to log out from, when force-logout is disabled.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Active connections associated to user [username] exist in one or more target receivers.” }
2.8.8.8 Response – Error: User not Logged in Receivers This error response indicates that the KVM user specified by the username parameter is not logged in to one or more target receivers.

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “User [username] is not logged in to one or more of the following receivers: [List of receiver names the user is not logged in].” }

2.8.9 API for Editing User Favorites as Global or to Zones This API is to edit the favorite settings for an existing KVM user in Boxilla, whose scope can be global or within a specific zone.

2.8.9.1 Request – Uri

Uri

bxa-api/users/kvm/favs

Method

POST

2.8.9.2 Request – Params Requirement Name
username
scope
Mandatory
settings

Type
String String
JSON object

Description
Name of the KVM user with the favorite settings to be edited. Scope of the favorite settings for the KVM user. Valid values include: “” (empty string value) or a valid name of an existing zone in Boxilla. If scope is set as “”, the user favorite is configured as global in Boxilla and not assigned to any individual zone. Details of favorite settings for this user, containing a list of key/value pairs:
· key: the index number of the favorite hotkey where the connection is allocated in the favorite, string format with valid numeric values from “0” “9”
· value: name of connection allocated to the related hotkey number, string format, can be empty value indicating that the connection is unallocated

2.8.9.3 Request Body JSON Format
{ “username”: “[username]”, “scope”: “” | “[zone_1]” | “[zone_2]” …., “settings”: { “[favorite/hotkey_number]”: [name of the connection allocated to hotkey], … // Potentially multiple settings key/value pairs, up to 10 with key ranging from “0” “9” }

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
}

The following example of the request body shows how the favorite numbers and connection names are matched with each other in the “settings” parameter:
{ “username”: “user1”, “scope”: “zone1”, “settings”: { “0”: “connection1”, “3”: “connection4” }
}
The example request above allocates connection “connection1” to hotkey 0 and connection “connection4” to hotkey 3, and assigns the user favorite to zone “zone1” for user “user1”.
2.8.9.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1.1
Body:
{ “code”: “200”, “message”: “Successfully updated favorite settings for user [username] to [scope].” }
2.8.9.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:
· Parameters are passed in as invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]. ”
· No KVM user exists with the specified username parameter in the request body. The associated error message in the response body is as follows: “message”: “User [username] does not exist.”
· No zone exists with the specified scope parameter in the request body, if the value is not global. The associated error message in the response body is as follows: “message”: “Zone [scope] does not exist for favorite settings for user [username].”
· One or more connections in the favorite settings JSON object do not exist. The associated error message in the response body is as follows:

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
“message”: “One or more connections do not exist.” · One or more connections in the favorite settings do not belong to the specified user. The
associated error message in the response body is as follows: “message”: “One or more connections in favorite settings do not belong to user [username].”
2.8.9.6 Response – Error: Connection not Assigned to Zone This error response indicates that one or more connections specified in the settings parameter are not assigned to the specified zone.
HTTP/1.1 403 Forbidden Accept: application/json; Content-Type: application/json; Accept-version: v1.1
Body:
{ “code”: “403”, “message”: “Connection [connection_name] is not in zone [zone_name].” }
2.8.9.7 Response – Error: Favorite Settings Exceeding Limit This error response indicates that the number of favorite settings exceeds limit of 10, as favorite number is limited to 0-9.
HTTP/1.1 403 Forbidden Accept: application/json; Content-Type: application/json; Accept-version: v1.1
Body:
{ “code”: “403”, “message”: “Favorite settings exceeding limit.” }
2.8.9.8 Response – Error: Duplicate Favorite Number for Multiple Connections This error response indicates that within the settings JSON object array parameter, multiple different connections are allocated to duplicate favorite number.
HTTP/1.1 403 Forbidden Accept: application/json; Content-Type: application/json; Accept-version: v1.1
Body:

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

{ “code”: “403”, “message”: “Duplicate favorite number detected in request with multiple connection allocated.” }
2.8.9.9 Response – Error: Duplicate Connections for Multiple Favorite Numbers This error response indicates that within the settings JSON object array parameter, duplicate connections are allocated to multiple different favorite numbers.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1.1
Body:
{ “code”: “403”, “message”: “Duplicate connection detected in request allocated to multiple favorite numbers.” }
2.9 APIs for Device-oriented Operations

The APIs for device operations include functionalities as follows:

· Get KVM receivers/transmitters · Get all properties set on each KVM appliance · Get KVM appliance status and information · Set properties of KVM appliances · Reboot specific/all KVM appliances

The associated design of each API is listed as follows:

2.9.1 API for Getting KVM Appliances This API is to obtain the list of all the receivers/transmitters managed on the host Boxilla. Valid property parameters are listed in the parameter table below.

2.9.1.1 Request – Uri

Uri

bxa-api/devices/kvm

Method

GET

2.9.1.2 Request Params

Requirement Name

Type

Optional

device_type String

Description
Type of device. Valid values are “transmitter” or “receiver”.

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Note:

device_names String array

List of names of KVM appliances to be obtained.

· If device_names parameter is null, the operation would be considered as getting all KVM appliances and the response is returned accordingly.
· If device_names parameter is an empty array, the API request is successful but the “devices” JSON array in the response body would be empty.
· If device_names is not null and contains valid device names, the value of device_type parameter would be ignored.
· If device_names is null and device_type is “transmitter” or “receiver”, the response would only contain the list of all the transmitters/receivers, respectively.

2.9.1.3 Request Body JSON Format
{ “device_type”: “receiver” | “transmitter”, “device_names”: [“[device_1]”, “[device_2]”, ….] }

// Optional, can be null // Optional, can be null or empty array

2.9.1.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: { “devices”: [
{ “name”: “[device_name]”, “ip”: “[ip]”, “mac”: “[MAC address]”, “model”: “[sales part number]”, “swversion”: “[firmware version]”, “serialno”: “[serial number]” }, …. // Multiple appliances ] } }

2.9.1.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API)
returned, which might include:

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”
· “device_names” parameter value is not an array or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter device_names: [device_names], expecting a String array.”
· One or more KVM appliances specified in the device_names parameter do not exist. The associated error message in the response body is as follows: “message”: “The following device(s) do(es) not exist: [List of device_names do not exist].”

2.9.2 API for Getting KVM Appliance Properties

This API is to obtain the property settings of each KVM appliance managed by the host Boxilla. Valid property parameters are listed in the parameter table below.

2.9.2.1 Request – Uri

Uri

bxa-api/devices/kvm/properties

Method

GET

2.9.2.2 Request Params

Requirement Name

Optional
Note:

device_names

Type
String array

Description
List of names of the KVM devices managed in Boxilla.

· If device_names parameter is null, the operation would be considered as getting all KVM appliance properties and the response is returned accordingly.
· If device_names parameter is an empty array, the API request is successful but the “properties” JSON array in the response body would be empty.

2.9.2.3 Request Body JSON Format { “device_names”: [“[device-1]”, “[device-2]”, ….] }
2.9.2.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: {

// Optional, can be null or empty array

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“properties”: [ { “device_name”: “[device_name]”, “property_state”: “Configured” | “Waiting” | “Configuring”, “model”: “[sales part number]”, “swversion”: “[firmware version]”, “zone”: “[name of the zone to which the receiver is assigned]” // If device is receiver, available from API version 1.1 [List of supported properties] }, {….}, // If multiple properties …. ] } } Note:
In the response body, the “list of supported properties” tag composes of the properties supported by the requested KVM device, which may be different based on the manufactory brand/class and the firmware version of the KVM device. The full supported list of properties for various types of KVM devices is listed in table 2 in the appendix section 4.1.
The following three examples show cases of the JSON element in “properties” JSON array in the response body, with various values of keys determining the type of device.
Example 1:
{ “device_name”: “transmitter-A”, “property_state”: “Configured”, “model”: “EMD2002SE-T”, “swversion”: “V5.3.1_r5666”, “video_quality”: “Default”, “video_source_optimization”: “Off”, “hid_configurations”: “3”, “mouse_keyboard_timeout”: “0”, “edid_settings_dvi1”: “1920×1080”, “edid_settings_dvi2”: “1920×1200”
}

Example 2:

{
“device_name”: “transmitter-B”, “property_state”: “Configured”, “model”: “EMD4000T”, “swversion”: “V1.3.1_r5639”,

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“hid_configurations”: “3”, “mouse_keyboard_timeout”: “0” }
Example 3:
{ “device_name”: “receiver-A”, “property_state”: “Configured”, “model”: “EMD2000SE-R”, “swversion”: “V5.4.0_r6438”, “zone”: “zone 1”, // available from API version 1.1 “config”: “Unique”, “http_enabled”: “Enabled”
}
2.9.2.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:
· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”
· “device_names” parameter value is not an array or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter device_names: [device_names], expecting a String array.”
· One or more KVM appliances specified in the device_names parameter has corrupted typerelated properties. The associated error message in the response body is as follows: “message”: “Invalid property configuration for device [name of the device]: property conflict or missing.”
· One or more KVM appliances specified in the device_names parameter do not exist. The associated error message in the response body is as follows: “message”: “The following device(s) do(es) not exist: [List of device_names do not exist].”

2.9.3 API for Setting KVM Receiver Properties

This API is to update the unique property settings of individual KVM receiver managed by the host Boxilla. Valid property parameters are listed in the parameter table below.

2.9.3.1 Request – Uri

Uri

bxa-api/devices/kvm/properties/rx

Method

PUT

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.9.3.2 Request Params Requirement Name
device_name http_enabled Mandatory zone

Type
String String
String

Description
Name of the KVM receiver managed in Boxilla. Maximum length 255. HTTP-enabled property to set. Valid values are “Enabled” or “Disabled”. Name of the zone this receiver is assigned to. Maximum length 32. This parameter is only applicable from API version 1.1 or newer. If parameter value is empty string, receiver would be unassigned from the zone it is currently assigined to (if any).

2.9.3.3 Request Body JSON Format
{ “device_name”: “[device_name]”, “http_enabled”: “Enabled” | “Disabled”, “zone”: “[name of the zone to which the receiver is assigned]” // can be empty string value }

2.9.3.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Receiver settings have been updated successfully.” }
2.9.3.5 Response Error: bad request This error response may be caused by:

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

· The property parameter values in the API request body are invalid or incompatible. The associated error message in the response body is as follows: “message”: “Parameters [list of params] are invalid or incompatible with firmware of receiver [device_name].”
· Receiver is offline. The associated error message in the response body is as follows: “message”: “Device [device_name] is offline. ”
· Operation fails on the receiver due to internal issues of the device firmware. The associated error message in the response body is as follows: “message”: “Device [device_name] is currently not functional.”
· The zone to be assigned does not exist on Boxilla. The associated error message in the response body is as follows: “message”: “Zone [zone] does not exist.”
2.9.3.6 Response Error: attempting to set unique properties for receiver configured with non-unique properties
This error response indicates that the specified receiver in request parameters is configured with template or system properties at the moment. As northbound REST API version 1 supports unique device property configuration only, in this case the operation would be forbidden.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Receiver [device_name] is with template/system properties. Editing is enabled for unique properties only.” }
2.9.3.7 Response Error: receiver firmware not supporting editing properties This error response indicates that the version of firmware deployed on the specified receiver in request parameters does not support editing properties. Usually this is caused by older versions of firmware without the associated appliance API.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”,

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“message”: “Firmware [firmware version] of [receiver model] receiver [device_name] does not support editing settings.” }

2.9.4 API for Setting KVM Transmitter Properties

This API is to set the property settings of individual KVM transmitter managed by the host Boxilla. Valid property parameters are listed in the parameter table below.

2.9.4.1 Request – Uri

Uri

bxa-api/devices/kvm/properties/tx

Method

PUT

2.9.4.2 Request Params

Requirement Name

Type Description

Mandatory Conditional

device_name video_quality video_source_optimization
hid_configurations
mouse_keyboard_timeout

String String String
String
String

Name of the KVM transmitter managed in Boxilla. Maximum length 255.
Video quality property to set. Valid values are “Best Quality”, “2”, “Default”, “4” or “Best Compression”. (Case sensitive) Supported by single/dual-head Emerald-SE/EmeraldPE transmitters and ZeroU transmitters.
Video source optimization property to set. Valid values are “Off”, “DVI/DP Optimised”, “VGA High Performance”, “VGA – Optimised” or “VGA – Low Bandwidth”. (Case sensitive) Supported by single-head Emerald-SE/Emerald-PE and ZeroU transmitters.
HID property to set. Valid values are integer formatted strings from 0-5, which represents: 0 Default; 1 Basic; 2 MAC; 3 Absolute; 4 Absolute MAC; 5 Dual Mouse 0-3 are supported by all types of transmitters. 4 is supported by single/dual-head EmeraldSE/Emerald-PE and ZeroU with firmware version no older than 5.3.0, and Emerald-4K with firmware version no older than 1.3.1. 5 is supported by single/dual-head EmeraldSE/Emerald-PE and ZeroU with firmware version no older than 5.4.1, and Emerald-4K with firmware version no older than 1.3.1.
Mouse-keyboard timeout property to set. Valid values are integer formatted strings from 0-5, representing timeout in seconds. Supported by all single/dual-head EmeraldSE/Emerald-PE and ZeroU transmitters, and Emerald-4K transmitters with firmware version no older than 1.4.0.

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

edid_settings_dvi1 edid_settings_dvi2

String String

EDID DVI property to set for head 1 on transmitter.

Valid values are “1920×1080”, “1920×1200”,

“1680×1050”, “1280×1024” and “1024×768” for

Emerald-SE/PE/ZeroU transmitters, and “Default”,

“3840x2160p-60Hz”,

“3840x2160p-30Hz”,

“2560x1440p-60Hz”, “1920x1080p-60Hz” for

Emerald-4K transmitters. (Case sensitive)

Supported by all single/dual-head Emerald-

SE/Emerald-PE and ZeroU transmitters, and

Emerald-4K transmitters with firmware version no

older than 1.4.0.

EDID DVI property to set for head 2 on transmitter

(Dual-head only).

Valid values are the same with edid_settings_dvi1.

Supported by dual-head Emerald-SE and Emerald-PE

transmitters.

Note: for EDID DVI properties, this API does not support “Clone” as a valid value, which is different from the API to get transmitter properties.

2.9.4.3 Request Body JSON Format
// Only “device_name” is mandatory, the rest parameters are conditionally applicable as described above

{
“device_name”: “[device_name]”, “video_quality”: “Best Quality” | “2” | “Default” | “4” | “Best Compression”, “video_source_optimization”: “Off” | “DVI/DP Optimised” | “VGA – High Performance” | “VGA Optimised” | “VGA – Low Bandwidth”, “hid_configurations”: “0” | “1” | “2” | “3” | “4” | “5”, “mouse_keyboard_timeout”: “0” | “1” | “2” | “3” | “4” | “5”, “edid_settings_dvi1”: “1920×1080” | “1920×1200” | “1680×1050” | “1280×1024” | “1024×768” (5 possible values for Emerald-SE/PE/ZeroU) | “Default” | “3840x2160p-60Hz” | “3840x2160p-30Hz” | “2560x1440p-60Hz” | “1920x1080p-60Hz” (5 possible values for Emerald-4K), “edid_settings_dvi2”: “1920×1080” | “1920×1200” | “1680×1050” | “1280×1024” | “1024×768” }

2.9.4.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Transmitter settings have been updated successfully.” }

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.9.4.5 Response Error: bad request This error response may be caused by:

· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”
· The specified device has corrupted type-related propeties. The associated error message in the response body is as follows: “message”: ” Unknown type of device [device_name]. Device properties might be missing or corrupted.”
· Transmitter is not found on Boxilla. The associated error message in the response body is as follows: “message”: “Device [device_name] does not exist. ”
· The property parameter values in the API request body are invalid or incompatible. The associated error message in the response body is as follows: “message”: “Parameters [list of params] are invalid or incompatible with firmware of transmitter [device_name].”

The following response shows an example of incompatible parameters:

HTTP/1.1 400 Bad Request
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “400”, “message”: “Parameters `video_quality’ and `video_source’ are invalid or incompatible with firmware of transmitter `Emerald4K-TX-1′.” }
2.9.4.6 Response Error: attempting to set unique properties for transmitter configured with non-unique properties
This error response indicates that the specified transmitter in request parameters is configured with template or system properties at the moment. As northbound REST API version 1 supports unique device property configuration only, in this case the operation would be forbidden.

HTTP/1.1 403 Forbidden Accept: application/json; Content-Type: application/json; Accept-version: v1
Body:
{

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“code”: “403”, “message”: “Transmitter [device_name] is with template/system properties. Editing is enabled for unique properties only.” }
2.9.4.7 Response Error: transmitter firmware not supporting editing properties This error response indicates that the version of firmware deployed on the specified transmitter in request parameters does not support editing properties. Usually this is caused by older versions of firmware without the associated appliance southbound REST API.

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Firmware [firmware version] of [transmitter model] transmitter [device_name] does not support editing settings.” }

2.9.5 API for Setting KVM Receiver Zone assignment This API is to update the zone the specified receiver is assigned to.

2.9.5.1 Request – Uri

Uri

bxa-api/devices/kvm/rx/zones

Method

POST

2.9.5.2 Request Params Requirement Name

Type

device_name String

Mandatory zone

String

Description
Name of the KVM receiver managed in Boxilla. Maximum length 255. Name of the zone this receiver is assigned to. Maximum length 32. If provided with an empty string value, receiver would be unassigned from the zone currently assigined to (if any).

2.9.5.3 Request Body JSON Format
{ “device_name”: “[device_name]”, “zone”: “[name of the zone to which the receiver is assigned]” }

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager
ENG-007-100100
2.9.5.4 Response Success Reassignment to New Specified Zone
HTTP/1.1 200 OK Accept: application/json; Content-Type: application/json; Accept-version: v1.1 Body:
{ “code”: “200”, “message”: “Receiver [device_name] has been successfully reassigned to zone [zone].” }
2.9.5.5 Response Success Unassignment to Original Zone (if any)
HTTP/1.1 200 OK Accept: application/json; Content-Type: application/json; Accept-version: v1.1 Body:
{ “code”: “200”, “message”: “Receiver [device_name] has been successfully unassigned from zone [original_zone].” }
2.9.5.6 Response Error: bad request This error response may be caused by:
· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”
· Receiver is not found on Boxilla. The associated error message in the response body is as follows: “message”: “Receiver [device_name] does not exist.”
· The zone to be assigned does not exist on Boxilla. The associated error message in the response body is as follows: “message”: “Zone [zone] does not exist.”
· Receiver is offline. The associated error message in the response body is as follows: “message”: “Receiver [device_name] is offline.”
· Reassignment of receiver to zone fail due to the embedded software issue. The associated error message in the response body is as follows: “message”: “Receiver [device_name] is currently not functinoal.”

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.9.6 API for Getting KVM Appliance Status This API is to obtain the real-time status of one or more KVM appliances managed by the host Boxilla, including the following contents:

· Information of logged-in users (receiver-only) · Information of the zone it is assigned to. This is only applicable if the device is a receiver and
assigned to a zone, for API version >= 1.1. · Information of active connections · Physical online/offline status · Appliance setting update status:
o Waiting: setting update is initializing. o Configuring: setting update is processing. o Configured: setting update is complete. o Note: as editing appliance settings using APIs in section 2.8.3 and 2.8.4 involve
communications with appliances and may take extra time, this GET API should be used to monitor the configuration state of appliance settings as needed. · Appliance details: o Basic: name; model number; serial number; firmware version o A unique identifier generated internally by individual Boxilla instance at the initialization state of managing the device o Operational details: total/free memory/storage; uptime; load average in 1/5/15 minutes o Network details: mac; ip; netmask; gateway; broadcast; primary/secondary DNS; multicast-ip and master port

Valid property parameters are listed in the parameter table below.

2.9.6.1 Request – Uri

Uri

bxa-api/devices/kvm/status

Method

GET

2.9.6.2 Request Params

Requirement Name

Optional

device_names

Type
String array

Description
List of names of the KVM devices managed in Boxilla.

2.9.6.3 Request Body JSON Format
{ “device_names”: [“[device-1]”, “[device-2]”, ….] }

// Optional, can be null or empty array

2.9.6.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: { “devices”: [
{ “uid”: “[Unique identifier generated internally by Boxilla for each device]”, “device_type”: “receiver” | “transmitter”, “zone”: “[Name of the zone it is assigned to]”, // This is applicable only if device is receiver “logged_in user”: { // Available for request to receivers only, empty if no user logged in “username”: “[logged-in username]”, “type”: “active directory user” | “common user” }, “active_connections”: [ {
“active_connection_name”: “[active_connection_name]”, “active_connection_type”: “Private” | “Shared”, “active_connection_group”: “ConnectViaTx” | “VM” | “VMPool” | “VMHorizon” | “TXPair”, }, {….}, // if there are more active connections …. ], “state”: “Online” | “Offline”, “status”: “Waiting” | “Configuring” | “Configured”, “device_name”: “[appliance-name]”, “mac”: “[MAC address]”, “ip”: “[ip]” }, {….}, // if there are more appliances …. ] } }
2.9.6.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API)
returned, which might include:

· Parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.) The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]. ”
· One or more KVM devices specified by the device_names parameter do not exist on Boxilla. The associated error message in the response body is as follows: “message”: “The following device(s)do(es) not exist: [non_exist_device_names]. ”

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

· One or more KVM devices specified by the parameter are currently offline. The associated error message in the response body is as follows: “message”: “[offline_device_names] currently offline. ”

2.9.7 API for Rebooting all KVM Appliances

This API is to send reboot command to all KVM appliances managed by the host Boxilla.

2.9.7.1 Request – Uri

Uri

bxa-api/devices/kvm/reboot-all

Method

POST

2.9.7.2 Request Params This API does not require any parameters within the request body. The version of API is required to be included in the request header.

2.9.7.3 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “All KVM devices are successfully rebooted.” }

2.9.7.4 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API)
returned, which might include:

· One or more KVM devices to be rebooted are currently offline. The associated error message in the response body is as follows: “message”: “The following device(s) to reboot is(are) offline: [offline_device_names]. ”
· Rebooting operation fails on one or more devices due to internal issues. The associated error message in the response body is as follows: “message”: “Fail to reboot the following device(s): [List of device names where rebooting failed].”

2.9.7.5 Response – Error: Rebooting via API not Supported by Device Firmware This error response indicates that the firmwares on one or more devices specified in the parameters
do not support the associated device rebooting functionality required by this API.

HTTP/1.1 403 Forbidden

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Rebooting via northbound REST API is not supported by the following device(s): [List of devices not supporting rebooting].” }

2.9.8 API for Rebooting selected KVM Appliances

This API is to send reboot command to individual KVM appliance managed by the host Boxilla. Valid parameters are listed in the parameter table below.

2.9.8.1 Request – Uri

Uri

bxa-api/devices/kvm/reboot

Method

POST

2.9.8.2 Request Params

Requirement Name

Type

Optional

device_names

String array

Description
List of names of KVM devices managed in Boxilla to be rebooted.

2.9.8.3 Request Body JSON Format
{ “device_names”: [“[device-1]”, “[device-2]”, ….], }

// Optional, can be null or empty array

2.9.8.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “The selected KVM device(s) is(are) successfully rebooted.” }

2.9.8.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API)
returned, which might include:

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
· Parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]. ”
· “device_names” parameter value is not an array or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter device_names: [device_names], expecting a String array.”
· One or more KVM appliances specified in the device_names parameter do not exist. The associated error message in the response body is as follows: “message”: “The following device(s) do(es) not exist: [List of device_names do not exist].”
· One or more KVM devices to be rebooted are offline. The associated error message in the response body is as follows: “message”: “The following device(s) to reboot is(are) offline: [offline_device_names]. ”
· Rebooting operation fails on one or more devices due to internal issues. The associated error message in the response body is as follows: “message”: “Fail to reboot the following device(s): [List of device names where rebooting failed].”
2.9.8.6 Response – Error: Rebooting via API not Supported by Device Firmware This error response indicates that the firmwares on one or more devices specified in the parameters do not support the associated device rebooting functionality required by this API.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Rebooting via northbound REST API is not supported by the following device(s): [List of devices not supporting rebooting].” }

2.10 APIs for Connection-oriented Operations
The APIs for connection-related operations include the following functionalities:
· Create new KVM connections between multiple BlackBox entities (transmitters/receivers, VMs, etc. that exchange traffic)
· Edit existing KVM connection properties · Deleting existing KVM connection records · Make/break KVM active connections

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

In Boxilla, each KVM connection active record is categorized into the following list of groups, based on the type of traffic source in the connection:

· ConnectViaTx: the traffic source is a transmitter device · VM: the traffic source is a VM · VMPool: the traffic source is a group of VMs · VMHorizon: the traffic source is a VM with horizontal view · TXPair: dual traffic sources exist from multiple transmitters
Creating/editing of each group of KVM connection is designed with the specific set of properties for as input parameters, whose associated requirements are defined as follows:

· Mandatory: the parameter is required · Unique Params: the parameter is required when creating/editing unique connections, including
the following categories: o ConnectViaTx Params: the parameter is optionally applicable for viaTx connections o VM Params: the parameter is optionally applicable for VM connections o VMPool Params: the parameter is optionally appliable for VM pool connections o VMHorizon Params: the parameter is optionally applicable for VM horizontal connections o TXPair Params: the parameter is optionally applicable for TXPair connections
The following table defines the conditional parameters for each category of unique connection:

Requirement viaTx Params VM Params

Name extended_desktop usb_redirection audio persistent
cmode
username password extended_desktop usb_redirection

Type String String String String
String
String String String String

Description
Enabled/disabled option for extended desktop configuration. Valid values are “Yes” or “No”. (Case sensitive) Enabled/disabled option for USB redirection. Valid values are “Yes” or “No”. (Case sensitive) Enabled/disabled option for audio. Valid values are “Yes” or “No”. (Case sensitive) Enabled/disabled option for connection persistency. Valid values are “Yes” or “No”. (Case sensitive) Compression mode supported for 2K-4K compatibility feature. Valid values are “0” or “10”. “0” represents lossless mode and “10” represents optimized mode. Lossless mode 0 is valid only when the host of the connection is an Emerald-4K transmitter. Username credential used for BlackBox VM login. Optional. Valid value needs to be the username of an existing user. Password credential used for BlackBox VM login. Optional unless “username” is provided. Valid value needs to be in pair with a valid username. Enabled/disabled option for extended desktop configuration. Valid values are “Yes” or “No”. (Case sensitive)
Enabled/disabled option for USB redirection.

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Valid values are “Yes” or “No”. (Case sensitive)

audio

String

Enabled/disabled option for audio. Valid values are “Yes” or “No”. (Case sensitive)

Port number (in numeric format) of the VM connected to (if

port

String applicable).

Maximum length 5.

domain

String

Domain name of the VM connected to (if applicable). Maximum length 255.

nla

String

Enabled/disabled option for NLA. Valid values are “Yes” or “No”. (Case sensitive)

extended_desktop

String

Enabled/disabled option for extended desktop configuration. Valid values are “Yes” or “No”. (Case sensitive)

VM-Pool Params

usb_redirection

String

Enabled/disabled option for USB redirection. Valid values are “Yes” or “No”. (Case sensitive)

audio

String

Enabled/disabled option for audio. Valid values are “Yes” or “No”. (Case sensitive)

Username credential used for BlackBox VM login.

username

String Optional.

Valid value needs to be the username of an existing user.

VM-Horizon

Password credential used for BlackBox VM login.

Params

password

String Optional unless “username” is provided.

Valid value needs to be in pair with a valid username.

protocol

String

Protocol used for VM Horizon view connections. Valid value is “PCoIP” only. (Case sensitive)

host_2

String

IP/DNS address of the secondary traffic source of the KVM connection.

audio

String

Enabled/disabled option for audio. Valid values are “Yes” or “No”. (Case sensitive)

persistent

String

Enabled/disabled option for connection persistency. Valid values are “Yes” or “No”. (Case sensitive)

pairing_type

String

Pairing type specified for TxPair connection. Valid values are “1” or “2”.

TxPair Params

Orientation of dual paired views of TxPair connections. Required only when “pairing_type” is set to “2”.

orientation

String

Valid values are “H12”, “H21”, “V12” or “V21” (Case sensitive), where “H/V” stands for Horizontal/Vertical and

“12/21” represents destination from view 1 to view 2 or

reverse.

Address of the audio source.

audio_source

String

Required only when “audio” is set as “Yes”. Valid values are “1” or “2”, representing whether the audio

source is specified as the value of host or host_2.

Table 1. KVM Connection Property Dependency based on Group of Connection (viaTx/VM/VMPool/VMHorizon/TxPair)

The details of the API for each group of KVM connection are introduced in the sections below, respectively.

2.10.1 API for Creating KVM Connections

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

This API is to create a new KVM connection with type, group and properties specified within the parameters in request body.

2.10.1.1 Request – Uri

Uri

bxa-api/connections/kvm

Method

POST

2.10.1.2 Request – Params

Requirement Name

Type Description

name host group

Mandatory

connection_type

view_only

zone

viaTx Params
VM Params VM-Pool Params VM-Horizon Params TxPair Params

String String String
String String String

Name of the KVM connection. Maximum length 64. IP/DNS address of the primary traffic source of the connection. Value cannot be set if “group” is “VMPool”. Connection group category. Valid values are: “ConnectViaTx” | “VM” | “VMPool” | “VMHorizon” | “TXPair”. (Case sensitive) Connection type. Valid values are “Private” or “Shared”. (Case sensitive) Value is fixed to be “Private” when “group” is set as “VM”, “VMPool” or “VMHorizon”. Enabled/disabled view-only option. Valid values are “Yes” or “No”. (Case sensitive) Name of the zone this connection is assigned to. Maximum length 32. If provided with empty string value, connection is not assigned to any zone.
Required when “group” is “ConnectViaTx”. “usb_redirection” parameter value cannot be “Yes” if “connection_type” is “Shared”. “cmode” parameter value can be “0” only when the host of the connection is an Emerald-4K transmitter.
Required when “group” is “VM”.
Required when “group” is “VMPool”.
Required when “group” is “VMHorizon”.
Required when “group” is “TXPair”.

2.10.1.3 Request Body JSON Format viaTx Connections
{
“name”: “[connection_name]”, “host”: “[host]”, “group”: “ConnectViaTx”, “connection_type”: “Private” | “Shared”, “extended_desktop”: “Yes” | “No”, “usb_redirection”: “Yes” | “No”, “audio”: “Yes” | “No”, “persistent”: “Yes” | “No”, “view_only”: “Yes” | “No”,

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“cmode”: “0” | “10”, “zone”: “Zone 1” // Can be empty string }

2.10.1.4 Request Body JSON Format VM Connections
{
“name”: “[connection_name]”, “host”: “[host]”, “group”: “VM”, “connection_type”: “Private”, “username”: “[VM-login username]”, “password”: “[VM-login password]”, “extended_desktop”: “Yes” | “No”, “usb_redirection”: “Yes” | “No”, “audio”: “Yes” | “No”, “port”: “[port]”, “domain”: “[domain]”, “nla”: “Yes” | “No”, “view_only”: “Yes” | “No” }

2.10.1.5 Request Body JSON Format VM-Pool Connections
{
“name”: “[connection_name]”, “host”: “[host]”, “group”: “VMPool”, “connection_type”: “Private”, “extended_desktop”: “Yes” | “No”, “usb_redirection”: “Yes” | “No”, “audio”: “Yes” | “No”, “view_only”: “Yes” | “No” }

2.10.1.6 Request Body JSON Format VM-Horizon Connections
{
“name”: “[connection_name]”, “host”: “[host]”, “group”: “VMHorizon”, “connection_type”: “Private”, “username”: “[VM-login username]”, “password”: “[VM-login password]”, “protocol”: “PCoIP”, “view_only”: “Yes” | “No” }

2.10.1.7 Request Body JSON Format TxPair Connections { “name”: “[connection_name]”,

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“host”: “[host]”, “host_2”: “[host_2]”, // Optional “group”: “TXPair”, “connection_type”: “Private” | “Shared”, “audio”: “Yes” | “No”, “persistent”: “Yes” | “No”, “view_only”: “Yes” | “No”, “pairing_type”: “1” | “2”, “orientation”: “H12” | “H21” | “V12” | “V21”, // applicable only when “pairing_type” is “2” “audio_source”: “1” | “2” // applicable only when “audio” is “Yes” }
2.10.1.8 Response – Success
HTTP/1.1 201 Created
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “201”, “message”: “Created [group] connection [name].” }
2.10.1.9 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:
· Property-related parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]. ”
· The zone to be assigned does not exist on Boxilla. The associated error message in the response body is as follows: “message”: “Zone [zone] does not exist.”
· Multiple property-related parameters are not compatible with each other, e.g. passing the connection_type parameter as “shared” together with the group parameter as “VM, “VMPool” or “VMHorizon”. (Check the parameter table for this API for details). The associated error message in the response body is as follows: “message”: “Parameters [List of incompatible parameters] are incompatible with [group] connection [name].” The following response shows an example of incompatible parameters:
HTTP/1.1 400 Bad Request
Accept: application/json;
Content-Type: application/json;

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Accept-version: v1
Body:
{ “code”: “400”, “message”: “Parameters `connection_type’: `Shared’ are incompatible with VM connection `connection-1′.” }
2.10.1.10 Response – Error: License-related Failure This error response indicates that the Boxilla license installed on the server is invalid, expired or limitation of the maximum number of users is reached.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “License limit reached.” }

2.10.1.11 Response – Error: Connection Already Exists This error response indicates that a KVM connection with the name specified in request body already exists and the API is attempting to create a duplicate record.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Duplicate name received.” }

2.10.2 API for Editing KVM Connection Profiles/Properties

This API is to edit the profile/properties of an existing KVM connection whose type, group and properties are specified within the parameters in request body.

2.10.2.1 Request – Uri

Uri

bxa-api/connections/kvm

Method

PUT

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.10.2.2 Request – Params

Requirement Name

Type Description

name host group

Mandatory

connection_type view_only

zone

Optional

new_name

viaTx Params
VM Params VM-Pool Params VM-Horizon Params TxPair Params

String String String String String
String
String

Name of the KVM connection. Maximum length 64. IP/DNS address of the primary traffic source of the connection. Value cannot be set if “group” is “VMPool”. Connection group category. Valid values are: “ConnectViaTx” | “VM” | “VMPool” | “VMHorizon” | “TXPair”. (Case sensitive) Connection type. Valid values are “Private” or “Shared”. (Case sensitive) Value is fixed to be “Private” when “group” is set as “VM”, “VMPool” or “VMHorizon”. Enabled/disabled view-only option. Valid values are “Yes” or “No”. (Case sensitive) Name of the zone this connection is assigned to. Maximum length 32. This parameter is only applicable from API version 1.1 or newer. If parameter is provided with empty string, connection would be unassigned from the zone it is currently assigined to (if any). New name of the KVM connection to be edited. Maximum length 64. Connection name is updated if provided. Required when “group” is “ConnectViaTx”. “usb_redirection” parameter value cannot be “Yes” if “connection_type” is “Shared”. “cmode” parameter value can be “0” only when the host of the connection is an Emerald-4K transmitter.
Required when “group” is “VM”.
Required when “group” is “VMPool”.
Required when “group” is “VMHorizon”.
Required when “group” is “TXPair”.

2.10.2.3 Request Body JSON Format For each group of connection (viaTx, VM, VM-Pool, VM-Horizon or TxPair), the request is individually defined in the same JSON format specified in section 2.9.1.3 – 2.9.1.7, respectively, with the additional “new_name” parameter available. If the “new_name” parameter is specified with a valid value (nameformat string; max-length 64; obeying the naming rules defined in section 4.3.1), the name of the connection would be updated with the value.

2.10.2.4 Response – Success
HTTP/1.1 200 OK Accept: application/json; Content-Type: application/json;

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Updated properties for connection [name].” }
2.10.2.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:
· Property-related parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]. ”
· Multiple property-related parameters are not compatible with each other, e.g. passing the connection_type parameter as “shared” together with the group parameter as “VM, “VMPool” or “VMHorizon”. (Check the parameter table for this API for details). The associated error message in the response body is as follows: “message”: “Parameters [List of incompatible parameters] are incompatible with [group] connection [name].”
· The associated KVM connection record does not exist. The associated error message in the response body is as follows: “message”: “Connection [name] does not exist.”
· The zone to be assigned does not exist on Boxilla. The associated error message in the response body is as follows: “message”: “Zone [zone] does not exist.”
2.10.2.6 Response Error: Attempting to Edit Properties of non-Unique Connections This error response indicates that the specified connection is with non-unique properties. Editing properties of the connection would be prohibited by the northbound REST API and a HTTP 403 error response is returned. The associated error message in the response body is as follows:
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: ” Editing properties for non-unique connection [name] is not supported.” }

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.10.2.7 Response Error: Changing Connection Name to Name of Existing Connection This error response indicates that the new connection name to be changed to belongs to an existing connection. The associated error message in the response body is as follows:

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Cannot update connection name to [new_name]. Connection [new_name] already exists.” }

2.10.3 API for Deleting all KVM Connections This API is to delete all the existing KVM connections with unique properties in Boxilla.

2.10.3.1 Request – Uri

Uri

bxa-api/connections/kvm/all

Method

DELETE

2.10.3.2 Request Params This API does not require any parameters within the request body. The version of API is included in the request header.

2.10.3.3 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Successfully deleted all connections.” }

2.10.3.4 Response – Error: Connection is Active This error response indicates that one or more KVM connections to be deleted are active with traffic
delivery when the request is being operated.

HTTP/1.1 409 Conflict Accept: application/json;

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “409”, “message”: ” Fail to delete connection(s) [connection_names] because one or more connections are active.” }

2.10.4 API for Deleting Specific KVM Connections This API is to delete one or more existing KVM connections with unique properties in Boxilla, specified by the request parameter which contains a list of existing connection names to be deleted.

2.10.4.1 Request – Uri

Uri

bxa-api/connections/kvm

Method

DELETE

2.10.4.2 Request – Params

Requirement Name

Type Description

Mandatory

connection_names

String array

List of names of the KVM connections to be deleted. If array is empty with no connection names inside, the API request is successful but no connection would be deleted.

2.10.4.3 Request Body JSON Format
{ “connection_names”: [“[connection_1]”, “[connection_2]”, …] // Mandatory, can be empty array }

2.10.4.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Successfully deleted connection(s) [connection_names].” }
2.10.4.5 Response Success with Empty Connection_names Parameter
HTTP/1.1 204 No Content
Accept: application/json;
Content-Type: application/json;

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
Accept-version: v1
2.10.4.6 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:
· Required parameters are passed in as empty (null parameter, not parameter as an empty array) or invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· “connection_names” parameter is not an array (for example, an integer is given instead) or any elements within are not String type. The associated error message in the response body is as follows:
· “message”: “Invalid parameter connection_names: [connection_names], expecting a String array.”
· One or more KVM connections specified in the connection_names parameter do not exist. The associated error message in the response body is as follows: “message”: “The following connection(s) [connection_names] do(es) not exist.”
2.10.4.7 Response Error: Attempting to Delete Connections with non-Unique Properties This error response indicates that one or more KVM connections specified in the parameters are with non-unique properties. Deleting these connections would be prohibited by the northbound REST API and a HTTP 403 error response is returned. Meanwhile all the other valid connections specified in the parameters would still be successfully deleted.
The associated error message in the response body is as follows:
HTTP/1.1 403 Forbidden Accept: application/json; Content-Type: application/json; Accept-version: v1
Body:
{ “code”: “403”, “message”: “The following connections are with non-unique properties: [List of connection names].” }
2.10.4.8 Response – Error: Connection is Active This error response indicates that one or more KVM connections to be deleted are active with traffic delivery when the request is being operated.
HTTP/1.1 409 Conflict Accept: application/json;

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “409”, “message”: ” Fail to delete connection(s) [connection_names] because one or more connections are active.” }

2.10.5 API for Getting KVM Connection Status This API is for obtaining status and related information of one or more KVM connections in Boxilla, including the following contents:

· Name of user that logs into the KVM appliance of the connection · Connection type: Private or Shared · Connection group: ConnectViaTx, VM, VM-pool, VM-horizon or TXPair · A unique identifier generated internally by individual Boxilla instance at the initialization state
of creating the connection

Valid property parameters are listed in the parameter table below.

2.10.5.1 Request – Uri

Uri

bxa-api/connections/kvm

Method

GET

2.10.5.2 Request Params

Requirement Name

Type

Description

Optional
Note:

connection_names String array List of names of the queried KVM connections

If no parameter is provided by the API request (parameter is null, not an empty array), the operation would be considered as getting status of all KVM connections and the response is returned accordingly.

If the “connection_names” parameter is an empty array, the API request is successful but no connection status is returned in the response (the “connections” JSON array in response body is empty).

2.10.5.3 Request Body JSON Format
{ “connection_names”: [“[connection_1]”, “[connection_2]”, …] empty array }

// Optional, can be null or

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.10.5.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: { “connections”: [
{ “uid”: “[Unique identifier generated internally by Boxilla for each connection]”, “name”: “[connection_name]”, “host”: “[IP/DNS of primary connection source]”, “connection_type”: “Private” | “Shared”, “group”: “ConnectViaTx” | “VM” | “VMPool” | “VMHorizon” | “TXPair”, “zone”: “[name of the zone to which the connection is assigned]”, “view_only”: “Yes” | “No”, [List of supported properties] }, {….}, // if there are more connections …. ] } } Note:

In the response body, the “list of supported properties” tag composes of the properties of the requested KVM connection, which may be different based on the group of connection. The full supported list of properties for each group of connection is listed in table 1 at the beginning of section 2.9.

“Password” property for VM/VMHorizon connection would NOT be returned.
The following three examples show cases of the JSON element in “connections” JSON array in response body for various groups of KVM connections.

Example 1:

{
“name”: “tx-connection-1”, “host”: “10.0.2.20”, “connection_type”: “Shared”, “group”: “ConnectViaTx”, “zone”: “zone 1”,
“extended_desktop”: “Yes”,

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“usb_redirection”: “No”, “audio”: “Yes”, “persistent”: “Yes”, “view_only”: “No”, “cmode”: “10”
}

Example 2:
{ “name”: “vm-connection-2”, “host”: “10.0.2.21”, “connection_type”: “Private”, “group”: “VM”, “username”: “James”, “extended_desktop”: “Yes”, “usb_redirection”: “No”, “audio”: “Yes”, “port”: “3389”, “domain”: “test.com”, “nla”: “Yes”, “view_only”: “No”
}
Example 3:
{ “name”: “txpair-connection-3”, “host”: “10.0.2.22”, “connection_type”: “Private”, “group”: “TXPair”, “host_2”: “10.0.2.23”, “audio”: “Yes”, “persistent”: “Yes”, “view_only”: “No”, “pairing_type”: “2”, “orientation”: “H12”, “audio-source”: 1
}
2.10.5.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:
· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

· “connection_names” parameter is not an array (for example, an integer is given instead) or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter connection_names: [connection_names], expecting a String array.”
· One or more KVM connections within the connection_name parameter do not exist. The associated error message in the response body is as follows: “message”: “The following connection(s) do(es) not exist: [List of connections do not exist]”

2.10.6 API for Launching KVM Active Connections This API is for launching a KVM active connection based on an existing KVM connection record. Requests of this API require authentication using the credentials of the REST API user described in section 2.3.2.

Before the operation of launching the connection, the user specified in the request is logged on to the target receiver forcefully by this API.

2.10.6.1 Request – Uri

Uri

bxa-api/connections/kvm/active

Method

POST

2.10.6.2 Request – Params Requirement Name

Type Description

username

String Name of the KVM user logged in to the receiver.

Mandatory

password connection_name receiver_name

String String String

Password of the KVM user logged in to the receiver.
Name of KVM connection as the active connection traffic source. Name of the receiver used to launch the active connection.

2.10.6.3 Request Body JSON Format { “username”: “[username]”, “psaaword”: “[password]”, “connection_name”: “[connection_name]”, “receiver_name”: “[receiver_name]” }
2.10.6.4 Response – Success
HTTP/1.1 201 Created
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

{ “code”: “201”, “message”: “Active connection [connection_name] is successfully launched.” }

2.10.6.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API)
returned, which might include:

· The source or destination (the receiver and transmitter/VM) does not exist. The associated error message in the response body is as follows: “message”: “Active connection [connection_name] or receiver [receiver_name] does not exist.”
· The user specified in the username parameter does not exist. The associated error message in the response body is as follows: “message”: “User [username] does not exist.”
· The source or destination (the receiver and transmitter/VM) is offline. The associated error message in the response body is as follows: “message”: “Active connection [connection_name] or receiver [receiver_name] is currently unreachable.”
· The embedded software on the KVM devices is mal-functional. The associated error message in the response body is as follows: “message”: “Active connection [connection_name] or receiver [receiver_name] is currently not functional.”

2.10.6.6 Response – Error: UnAuthorized This error response may be caused by:

2.10.6.7 Response – Error: Launching Active Connection not Supported by Device Firmware This error response indicates that the version of firmware deployed on the specified receiver in request parameters does not support launching active connections. Usually this is caused by older versions of firmware without the associated appliance southbound REST API.

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: ” Launching active connection is not supported by firmware type [receiver model] version [firmware version] of receiver [receiver_name].” }

2.10.6.8 Response – Error: Connection not Assigned to Logged-in User This error response indicates that the source KVM connection to be launched is not assigned to the logged-in KVM user on the receiver.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Connection [connection_name] not assigned to user [username].” }

2.10.6.9 Response – Error: User Login Timeout on Receiver This error response indicates that a timeout has occurred during the specified user login on the receiver.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “User [username] login timeout on receiver [receiver_name].” }

2.10.7 API for Terminating KVM Active Connections This API is to break an existing KVM active connection between a source/destination pair. Requests of this API require authentication using the credentials of the REST API user described in section 2.3.2.

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.10.7.1 Request – Uri

Uri

bxa-api/connections/kvm/active

Method

DELETE

2.10.7.2 Request – Params

Requirement Name

Type Description

Mandatory Optional

username connection_name receiver_name
splash_screen

String String String
String

Name of the KVM user logged in to the receiver.
Name of KVM connection as the active connection traffic source. Name of the receiver used to terminate the active connection
String indicating if the splash screen should be displayed following Connection Termination. Valid values are “Yes” or “No”.

2.10.7.3 Request Body JSON Format
{
“username”: “[username]”, “connection_name”: “[connection_name]”, “receiver_name”: “[receiver_name]”, “splash_screen”: “Yes” | “No” }

2.10.7.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Active connection [connection_name] is successfully terminated.” }
2.10.7.5 Response – Error: Bad Request This error response indicates any non-specific error (may be caused by internal errors within the API) returned, which might include:

Rev 1.9.4

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

· Receiver is offline. The associated error message in the response body is as follows: “message”: “Receiver [receiver_name] is unreachable.”
· The embedded software on the KVM device is mal-functional. The associated error message in the response body is as follows: “message”: “Active connection [connection_name] or receiver [receiver_name] is currently not functional.”
2.10.7.6 Response – Error: Terminating Active Connection not Supported by Device Firmware This error response indicates that the version of firmware deployed on the specified receiver in request parameters does not support terminating active connections. Usually this is caused by older versions of firmware without the associated appliance API.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: ” Terminating active connection is not supported by firmware type [receiver model] version [firmware version] of receiver [receiver_name].” }

2.10.7.7 Response – Error: Connection not Active This error response indicates that the specified connection in the parameter to be terminated is not active at the mome

Documents / Resources

BLACK BOX BXAMGR-R2 Boxilla KVM Manager [pdf] Instruction Manual
BXAMGR-R2 Boxilla KVM Manager, BXAMGR-R2, Boxilla KVM Manager, KVM Manager, Manager

References

User Manual

BXAMGR-R2 Boxilla KVM Manager

Product Information

Specifications

Product Usage Instructions

General Procedures

Northbound REST API URI Format

Frequently Asked Questions (FAQ)

Q: How can I update my REST username using the Boxilla REST
API?

Q: What are the key features introduced in the V1.9.4 release
of BXAMGR?

Documents / Resources

References

Leave a comment

Cancel reply