Alyvix Service API v4

This section describes version 4 of the Alyvix Service API methods in technical detail. 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.

Versioning Endpoint

This call lets you query the API version(s) this Alyvix Node can accommodate. Does not require any special permissions or knowing any current API version to be used.

GET /api_versions
Description:
	Retrieve the list of the supported and active API versions the node can handle.
Required/Optional Arguments:
	None
Example call:
	requests.get('https://<server:port>/api_versions', verify=False).json()
May return:
	{"supported": ["v3", "v4"], "active": ["v3", "v4"]}

Administrator Group

Endpoints intended for infrastructure admin use, identifiable by the prefix /v4/super-admin/

Admin Licensing Endpoints

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

GET /v4/super-admin/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>/v4/super-admin/license_status', verify=False).json()
May return:
	{"service_status": "ACTIVE", "license_instance_code": "<string>", "server_instance_code": "<string>", "subscription_plan": "NE Alyvix e+_sub", "expiration_date": "2027-03-31T00:00:00+02:00", "licensed_sessions": 15}

GET /v4/super-admin/license
Description:
	Retrieve the license request code of the specified Alyvix Node.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/super-admin/license', verify=False).json()
May return:
	{"license_request": "<string>"}

POST /v4/super-admin/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>/v4/super-admin/license', json={"license": "123"}, verify=False)

Admin Settings Endpoints

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

GET /v4/super-admin/settings
Description:
	Retrieve an Alyvix Node’s general settings.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/super-admin/settings', verify=False).json()
May return:
	{"private_key": "", "successful_retention_period": 19, "failed_retention_period": 72, "log_retention_period": 72, "all_annotation_images": true, "alyvix_service_version": "2.6.3", "disable_api_below_v3": true, "alyvix_core_version": "3.6.0b0", "nats_influxdb_versions": [1], "tenants": [{"id": 1, "name": "master", "timeperiods": []}, {"id": 2, "name": "wuerthphoenix", "timeperiods": [{"id": 1, "object_name": "tp1", "hash": "<string>"}]}]}

PUT /v4/super-admin/settings
Description:
	Set the same settings that are retrieved above.
Required Arguments:
	None
Optional Arguments:
	private_key (string) successful_retention_period (int) failed_retention_period (int, hours) log_retention_period (int, hours) log_level [DISABLED, ERROR, DEBUG] all_annotation_images (bool) disable_api_below_v3 (bool)
Example:
	requests.put('https://<server:port>/v4/super-admin/settings', json={"private_key":"123", "successful_retention_period": 24, "failed_retention_period": 72, "log_retention_period": 72, "log_level": "debug", "all_annotation_images": "true"}, verify=False)

Admin Tenancy Endpoints

Add, retrieve, update and remove records or information on individual tenants.

GET /v4/super-admin/tenants
Description:
	Retrieve the information for all tenants at once.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/super-admin/tenants', verify=False).json()
May return:
	[{"id": 1, "name": "master", "description": null}, {"id": 2, "name": "wuerthphoenix", "description": null}]

POST /v4/super-admin/tenants
Description:
	Update the entire list of tenants on this Alyvix Node.
Required Arguments:
	name (string) description (string)
Example:
	requests.post('https://<server:port>/v4/super-admin/tenants', json={"name":"tenant1", "description": "description1"}, verify=False)

GET /v4/super-admin/tenants/<tenant_id>
Description:
	Retrieve the information for a specific tenant.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/super-admin/tenants/3', verify=False).json()
May return:
	{"id": 1, "name": "master", "description": null}

PUT /v4/super-admin/tenants/<tenant_id>
Description:
	Update the description of the tenant identified by the ID on this Alyvix Node.
Required Arguments:
	description (string)
Example:
	requests.put('https://<server:port>/v4/super-admin/tenants/3', json={"description": "customer"}, verify=False)

DELETE /v4/super-admin/tenants/<tenant_id>
Description:
	Completely remove the specified tenant from this Alyvix Node.
Required/Optional Arguments:
	None
Example:
	requests.delete('https://<server:port>/v4/super-admin/tenants/3', verify=False)

Admin InfluxDB Endpoints

Add, retrieve, update and remove information on the connection between a tenant's data and a data stream.

GET /v4/super-admin/nats-influxdb
Description:
	Retrieve the information about the active NATS-InfluxDB channels through which data is flowing between this Alyvix Node and an InfluxDB.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/super-admin/nats-influxdb', headers={<header_dictionary>}, verify=False).json()
May return:
	{"nats-influxdb": [{"id": 3, "tenant_name": "master", "nats_ip_port": "<ip>:<port>", "nats_subject_name": "alyvix.metrics", "nats_influxdb_version": 1}]}

POST /v4/super-admin/nats-influxdb
Description:
	Add the configuration about of a new NATS-InfluxDB channel to activate on this Alyvix Node.
Required Arguments:
	tenant_name (string) nats_ip_port (string) nats_subject_name (string)
Example:
	requests.post('https://<server:port>/v4/super-admin/nats-influxdb', json={"tenant-name":"master", "nats_ip_port": "<ip>:<port>"}, "nats_subject_name": "alyvix.metrics"}, headers={<header_dictionary>}, verify=False)

GET /v4/super-admin/nats-influxdb/<channel_id>
Description:
	Retrieve the information for the database channel of a specific tenant.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/super-admin/nats-influxdb/3', verify=False).json()
May return:
	{id, tenant_name, nats_ip_port, nats_subject_name, nats_influxdb_version}

PUT /v4/super-admin/nats-influxdb/<channel_id>
Description:
	Update the configuration of an active NATS-InfluxDB channel (identified with its channel ID).
Required Arguments:
	tenant_name (string) nats_ip_port (string: "ip:port") nats_subject_name (string)
Example:
	requests.put('https://<server:port>/v4/super-admin/nats-influxdb/3', json={"tenant_name": "master", "nats_ip_port": "<ip>:<port>", "nats_subject_name": "alyvix.metrics"}, headers={<header_dictionary>}, verify=False)

DELETE /v4/super-admin/nats-influxdb/<channel_id>
Description:
	Completely remove the specified database connection from this Alyvix Node.
Required/Optional Arguments:
	None
Example:
	requests.delete('https://<server:port>/v4/super-admin/nats-influxdb/3', headers={<header_dictionary>}, verify=False)

Admin Logging Endpoints

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

GET /v4/super-admin/log
Description:
	Retrieve the list of annotated log messages on test case reports, filterable by date, source or severity level.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/super-admin/log', verify=False).json()
May return:
	{id, log_level, date, message domain, username line_number, line_text, function_name, class_name exception_type, filename}

POST /v4/super-admin/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 (string ∊ [DEBUG, WARNING, CRITICAL])
Optional Arguments:
	None
Example:
	requests.post('https://<server:port>/v4/super-admin/log', json={"log_level": "DEBUG", "message": "text"}, verify=False)

Tenant Group

Endpoints used only for a single specific tenant, identifiable by the prefix /v4/<tenant_name>/ where <tenant-name> cannot be admin.

Tenant Settings 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 /v4/<tenant_name>/settings
Description:
	Retrieve the top-level settings for the named tenant on this Alyvix Node.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/sessions', verify=False).json()
May return:
	{successful_retention_period, failed_retention_period, all_annotation_images, timeperiods: {[ id, object_name, hash], …}

Tenant Session Endpoints

Retrieve and set session information for a specific tenant on this Alyvix Node.

GET /v4/<tenant_name>/sessions
Description:
	Retrieve all the sessions of a specific tenant on this Alyvix Node.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/<tenant_name>/sessions', verify=False).json()
May return:
	{[id, tenant_id, domain, username, width, height scaling_factor, testcase_waiting_period, session_waiting_period, test_case_list: [[ enabled, id, name, tags: [[ id, name], …]], …] control, status, status_details: [[ test_case_id, test_case_id, test_case_name], …], …}

GET /v4/<tenant_name>/sessions/<session_id>
Description:
	Retrieve the details of a specific session for a specific tenant on this Alyvix Node.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/<tenant_name>/sessions/<session_id>', verify=False).json()
May return:
	{tenant_id, domain, username, width, height scaling_factor, testcase_waiting_period, session_waiting_period, test_case_list: [[ enabled, id, name, tags: [[ id, name], …]], …] control, status, status_details: [[ test_case_id, test_case_id, test_case_name], …}

PUT /v4/<tenant_name>/sessions/<session_id>
Description:
	Update the details of a specific session for a specific tenant on this Alyvix Node.
Required Arguments:
	control (string ∊ [PLAY, BREAK, STOP])) width (int, pixels) height (int, pixels) scaling_factor (int, percentage) test_case_list [[: id (int), enabled (bool)], …]
Optional Arguments:
	testcase_waiting_period (int) default: 0 session_waiting_period (int) default: 0
Example:
	requests.put('https://<server:port>/v4/acme/sessions/3', json={"control":"PLAY", "width": 1920, "height": 1080, "scaling_factor": 100, "test_case_list": [["id": "User04", "enabled": True]]}

Tenant Test Case Endpoints

Retrieve and set test case information for a specific tenant on this Alyvix Node.

GET /v4/<tenant_name>/testcase-filenames
Description:
	Retrieve the settings for the specified Session on this Alyvix Node.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/tenant1/testcase-filenames', json={"control": "break"}, :ep-black-s:`verify=False).json()
May return:
	{testcase_filenames: [<filename1>, <filename2>, …]}

GET /v4/<tenant_name>/testcases
Description:
	Retrieve the list of test cases belonging to a specific tenant that have been created on the current Alyvix Node and are thus available to be added to a Session.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/<tenant_name>/testcases', verify=False).json()
May return:
	{testcases: [[, id, tenant_id, name, filename, arguments, timeperiod_id, tags: [[ id, name], …]}

POST /v4/<tenant_name>/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) arguments (string) timeperiod_id (int) tags (string)       id (int)       name (string)
Example:
	requests.post('https://<server:port>/v4/<tenant_name>/testcases', json={"name": "visittrentino", "filename": "file01.alyvix", "arguments": "123", "timeperiod_id": 5, "tags": { "id": 3, “name": "HR"}}, verify= False)

GET /v4/<tenant_name>/testcases/<testcase_id>
Description:
	Retrieve the list of test cases belonging to a specific tenant that have been created on the current Alyvix Node and are thus available to be added to a Session.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/<tenant_name>/testcases/<testcase_id>', verify=False).json()
May return:
	{tenant_id, name, filename, arguments, timeperiod_id, tags: [[id, name], …]}

PUT /v4/<tenant_name>/testcases/<testcase_id>
Description:
	Add a 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 timeperiod_id (int) default null tags (list) default null       id (int)       name (string)
Example:
	requests.put('https://<server:port>/testcases/1', json={"filename": "file01.alyvix", "arguments": "123"}, verify=False)

DELETE /v4/<tenant_name>/testcases/<testcase_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>/v4/<tenant_name>/testcases/1', verify=False)

Tenant Measurement Endpoints

Retrieve measurements from all runs or a specific test case run for a specific tenant on this Alyvix Node.

GET /v4/<tenant_name>/testcases/<testcase_id>/measures GET /v4/<tenant_name>/testcases/<testcase_id>/measures/<runcode>
Description:
	Retrieve the list of recorded measures (all of them if not restricted) for a particular test case.
Required/Optional Arguments:
	None
Examples:
	requests.get('https://<server:port>/v4/tenant1/testcases/3/measures', verify=False).json() requests.get('https://<server:port>/v4/tenant1/testcases/3/measures/123', verify=False).json()
May return:
	{values: [tenant_id, user_id, hostname, domain, username, timestamp_epoch, test_case_execution_code, test_case_name, test_case_filename, test_case_alias, test_case_arguments, test_case_duration_ms, test_case_state, test_case_exit, transaction_name, transaction_group, transaction_alias, transaction_warning_ms, transaction_critical_ms, transaction_timeout_ms, transaction_performance_ms, transaction_accuracy_ms, transaction_detection_type, transaction_resolution_height, transaction_resolution_width, transaction_scaling_factor, transaction_record_text, transaction_record_extract, transaction_state, transaction_exit:, test_case_tags: [[, id, name], …]] …}

Tenant Time Period Endpoints

Retrieve, update and delete time periods for a specific test case run for a specific tenant on this Alyvix Node.

GET /v4/<tenant_name>/timeperiods GET /v4/<tenant_name>/timeperiods/<timeperiod_id>
Description:
	Retrieve all (or a specified) time periods for a particular tenant and test case.
Required/Optional Arguments:
	None
Examples:
	requests.get('https://<server:port>/v4/tenant1/timeperiods', verify=False).json() requests.get('https://<server:port>/v4/tenant1/timeperiods/3', verify=False).json()
May return:
	{id, object_name, display_name, ranges}

POST /v4/<tenant_name>/timeperiods POST /v4/<tenant_name>/timeperiods/<timeperiod_id> PUT /v4/<tenant_name>/timeperiods PUT /v4/<tenant_name>/timeperiods/<timeperiod_id>
Description:
	Add or update all (or a specified) time periods for a particular tenant.
Required Arguments:
	object_name (string) default null display_name (string) default null ranges (string, dictionary of days with timeperiods) default null
Example:
	requests.post('https://<server:port>/v4/tenant1/timeperiods/123', json={"object_name": "WD1", "display_name": "Weekdays", "ranges": ["'tuesday': '08:00-12:00, 13:00-18:00'"]}, verify=False)

DELETE /v4/<tenant_name>/timeperiod DELETE /v4/<tenant_name>/timeperiod/<timeperiod_id>
Description:
	Remove a specific existing time period by referencing its position in the list, or all time periods.
Required/Optional Arguments:
	None
Example:
	requests.delete('https://<server:port>/v4/<tenant_name>/testcases/1', verify=False)

Tenant Tagging Endpoints

Retrieve or create a tag under a specific tenant on this Alyvix Node.

GET /v4/<tenant_name>/tags
Description:
	Retrieve all tags used by this tenant.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/tenant1/tags', verify=False).json()
May return:
	{tags, [[tenant_id, id, name, description], …]}

POST /v4/<tenant_name>/tags
Description:
	Add a new tag to the tenant's existing tag list.
Required Arguments:
	name (string) description (string)
Example:
	requests.post('https://<server:port>/v4/<tenant_name>/tags', json={"name": "HR", "description": "text"}, verify=False)

GET /v4/<tenant_name>/tags/<tag_id>
Description:
	Retrieve the details for a specific tag used by this tenant on this Alyvix Node.
Required/Optional Arguments:
	None
Example:
	requests.get('https://<server:port>/v4/tenant1/tags/3', verify=False).json()
May return:
	{tenant_id, name, description}