Service Guide
Version v2.3.0

Alyvix Service API

This section describes in technical detail the Alyvix Service API methods. These methods are sufficient to allow you to integrate Alyvix Service into any monitoring system, which can then use its own graphical user interface to display data and launch actions.

API calls are based on a root URL of the form https://<alyvix_service_ip>:<port> where a GET, PUT, POST or DELETE call such as GET /license will result in a final URL of the form https://<alyvix_service_ip>:<port>/license.

All return values will be in JSON format. The included example invocations are written in Python.

Licensing Endpoints

These calls allow you to query and/or set licenses and license status.

GET /license

Description:

Retrieve the content of an existing license on the specified Alyvix Node.

Required/Optional Arguments:

None

Example:

requests.get(https://<server:port>/license, verify=False).json()


POST /license

Description:

Set the content of a license, replacing the current one if it exists.

Required Arguments:

license (string)

Optional Arguments:

None

Example:

requests.post(https://<server:port>/license, json={“license”: “123”}, verify=False).json()


GET /license_status

Description:

Retrieve the current status of the license for the specified Alyvix Node, returning the string “no” if not currently valid, and “yes” otherwise.

Required/Optional Arguments:

None

Example:

requests.get(https://<server:port>/license_status, verify=False).json()



Settings Endpoints

Change or retrieve the high level, general settings governing an entire Alyvix Node.

GET /settings

Description:

Retrieve an Alyvix Node’s general settings.

Required/Optional Arguments:

None

Example:

es. requests.get(https://<server:port>/settings, verify=False).json()


PUT /settings

Description:

Set the same settings that are retrieved above.

Required Arguments:

None

Optional Arguments:

private_key (string) default: null

successful_retention_period (int) default: 1

failed_retention_period (int) default: 3

log_retention_period (int) default: 7

log_level [disabled, error, debug] default: error

Example:

requests.put(“https://<server:port>/settings”, json={“private_key”:”123”, “successful_retention_period”: 1, “failed_retention_period”: 7, “log_retention_period”: 5, “log_level”: “debug”}, verify=False).json()



Session Endpoints

Retrieve or set both the top-level settings for all Sessions on the specified Alyvix Node, or the settings for a specific Session.

GET /sessions

Description:

Retrieve the top-level settings for all sessions on this Alyvix Node.

Required/Optional Arguments:

None

Example:

requests.get(https://<server:port>/sessions, verify=False).json()


POST /sessions

Description:

Update the settings for all Sessions on this Alvyix Node.

Required Arguments:

domain (string)

username (string)

password (string)

width (int)

height (int)

scaling_factor (int)

Optional Arguments:

testcase_waiting_period (int) default: 0

session_waiting_period (int) default: 0

Example:

requests.post(“https://<server:port>/sessions”, json={“domain”:”dm”, “username”: “AlyvixUser04”, “password”: “abc123”, “width”: 1920, “height”: 1080, “scaling_factor”: 100, “testcase_waiting_period”: 1, “session_waiting_period”: 5}, verify=False).json()


PUT /sessions/<id>

Description:

Update the settings for the specified Session on this Alyvix Node.

Required Arguments:

None

Optional Arguments:

password (string) default: null

width (int) default: null

height (int) default: null

scaling_factor (int) default: null

control [play, break, stop] default: null

test_case_list [{id, enabled}, {…}] default: null

testcase_waiting_period (int) default: 0

session_waiting_period (int) default: 0

Examples:

requests.put(“https://<server:port>/sessions/1”, json={“control”: “break”}, verify=False)

requests.put(“https://<server:port>/sessions/1”, json={“test_case_list”: [{“id”: 1, “enabled”: True}, {“id”: 2, “enabled”: False}]}, verify=False).json()

requests.put(“https://<server:port>/sessions/1”, json={“testcase_waiting_period”: 1, “session_waiting_period”: 5}, verify=False).json()


DELETE /sessions/<id>

Description:

Completely remove the specified Session from this Alyvix Node.

Required/Optional Arguments:

None

Example:

requests.delete(“https://<server:port>/sessions/1”, verify=False).json()



Test Case Endpoints

Retrieve, set or remove information about Alyvix test cases, including file names, settings, and data measures.

GET /testcase-filenames

Description:

Retrieve the list of file names in the configured test case directory on this Alyvix Node.

Required or Optional Arguments:

None

Example:

requests.get(“https://<server:port>/testcase-filenames”, verify=False).json()


GET /testcases

Description:

Retrieve the list of test cases that have been created on the current Alyvix Node and are thus available to be added to a Session.

Required or Optional Arguments:

None

Example:

requests.get(“https://<server:port>/testcases”, verify=False).json()


POST /testcases

Description:

Add a new test case configuration, with optional run time arguments, to the list of available test cases.

Required Arguments:

name (string)

filename (string)

Optional Arguments:

arguments (string) default null

Example:

requests.post(“https://<server:port>/testcases”, json={“name”: “visittrentino”, “filename”: “file01.alyvix”, “arguments”: “123”}, verify= False).json()


PUT /testcases/<id>

Description:

Add a newly user-created test case, overwriting a specific existing one (indicated by position).

Required Arguments:

None

Optional Arguments:

filename (string) default null

arguments (string) default null

Example:

requests.put(“https://<server:port>/testcases/1”, json={“filename”: “file01.alyvix”, “arguments”: “123”}, verify=False).json()


DELETE /testcases/<id>

Description:

Remove a specific existing test case by referencing its position in the list.

Required/Optional Arguments:

None

Example:

requests.delete(“https://<server:port>/testcases/1”, verify=False).json()


GET /testcases/<id>/measures

Description:

Retrieve the list of recorded measures (all of them if not restricted) for a particular test case.

Required Arguments:

None

Optional Arguments:

session_id (int) default all

test_case_from (string) default last runcode

test_case_to (string) default last runcode

test_case_screenshot (bool) default false

Example:

requests.get(“https://<server:port>/testcases/1/measures?test_case_from=20220501120000& test_case_to=20220631120000&test_case_screenshot=false”, verify=False).json()


GET /testcases/<id>/measures/<runcode>

Description:

Get a single test case measure by specifying the test case position and the code of the test case run.

Required Arguments:

None

Optional Arguments:

test_case_screenshot (bool) default false

Example:

requests.get(“https://<server:port>/testcases/1/measures/myserverDMAlyvixUser01 visittrentino1654073793?test_case_screenshot=false”, verify=False).json()



Logging Endpoints

Set or retrieve content and settings for creating annotations on individual test case runs.

GET /log

Description:

Retrieve the list of annotated log messages on test case reports, filterable by date, source or severity level.

Required Arguments:

None

Optional Arguments:

log_from (string) default null

log_to (string) default null

log_source [SERVER, CLIENT, EXTERNAL] default null

log_level [DEBUG, WARNING, CRITICAL] default null

Example:

requests.get(“https://<server:port>/log”, verify=False).json()


POST /log

Description:

Add a new annotation message to the log, specifying a severity level (date and source are automatic).

Required Arguments:

message (string)

log_level [DEBUG, WARNING, CRITICAL]

Optional Arguments:

None

Example:

requests.post(“https://<server:port>/log”, json={“log_level”: “DEBUG”, “message”: “text”}, verify=False).json()