Remote User API

Portal Server Remote User API Specification

Generating an Authentication Token

To perform a Remote User API call, you must first sign in into the portal and generate an “API Authentication Token”. When generating the token you can enter a purpose (only used as information) and also restrict the remote IP addresses for which the token is valid.

“alt attribute”

“alt attribute”

API Functions

The API supports the following functions (so-called “actions”):

Common Functions:

  • getUserAccountInfo (Get information about the own user account)
  • getPricePlanInfo (Get information about the current price plan)

Projects, Resource Sets and Files Functions:

  • getProjectTree (Get the project tree inclusive all resource sets and all file information)
  • createProject (Create a new project)
  • deleteProject (Delete a project)
  • getResourceSetsOfProject (Get all resource sets of a project, inclusive all file information)
  • createResourceSet (Create a new resource set)
  • deleteResourceSet (Delete a resource set)
  • getFilesInfoOfResourceSet (Get all files information of a resource set)
  • createFile (Create or overwrite a file)
  • getFile (Get the content of a file and the file information)
  • deleteFile (Delete a file)

Measuring Agents Functions:

  • getMeasuringAgents (Get all defined measuring agents)
  • getMinRequiredMeasuringAgentVersion (Get the minimum required measuring agent version)
  • addMeasuringAgent (Add a new measuring agent)
  • pingMeasuringAgent (Ping a measuring agent)
  • setMeasuringAgentActive (Set the state of a measuring agent to active or inactive)
  • deleteMeasuringAgent (Delete a measuring agent)

Measuring Agent Cluster Functions:

  • getMeasuringAgentClusters (Get all defined measuring agent clusters)
  • getClusterControllers (Get all cluster controllers and for each cluster controller a list of measuring agent clusters which are referencing the cluster controller)
  • getMinRequiredClusterControllerVersion (Get the minimum required cluster controller version)
  • pingClusterController (Ping a cluster controller)
  • addMeasuringAgentCluster (Add a new measuring agent cluster)
  • addMemberToMeasuringAgentCluster (Add a member to a measuring agent cluster)
  • removeMemberFromMeasuringAgentCluster (Remove a member from a measuring agent cluster)
  • pingMeasuringAgentClusterMembers (Ping the cluster members of a measuring agent cluster via cluster controller)
  • setMeasuringAgentClusterActive (Set the state of a measuring agent cluster to active or inactive)
  • deleteMeasuringAgentCluster (Delete a measuring agent cluster)

HTTP/S Remote Proxy Recorders Functions:

  • getProxyRecorders (Get all defined HTTP/S proxy recorders)
  • getMinRequiredProxyRecorderVersion (Get the minimum required HTTP/S proxy recorder version)
  • addProxyRecorder (Add a new HTTP/S proxy recorder)
  • pingProxyRecorder (Ping a HTTP/S proxy recorder)
  • deleteProxyRecorder (Delete a HTTP/S proxy recorder)
URL HTTP Method
https://portal.realload.com/RemoteUserAPI POST
All data are sent and received in JSON data format. The “authTokenValue” and the “action” must always be sent when an API call is made.

Example

API HTTP/S Request

curl -v --request POST --header "Content-Type: application/json" --data {\"authTokenValue\":\"jPmFClqeDUXaEk8Q274q\",\"action\":\"getUserAccountInfo\"}  https://portal.realload.com/RemoteUserAPI

API Request Data

{
  "authTokenValue": "jPmFClqeDUXaEk8Q274q",
  "action": "getUserAccountInfo"
}

API Response Data

{
  "userAccountInfo":{
    "userId":48,
    "nickname":"BET",
    "firstName":"Bettina",
    "lastName":"MeierHans",
    "primaryEmail":"bettina@meierhans.id.au",
    "primarySMSPhone":"+61401111111",
    "secondaryEmail":"",
    "secondarySMSPhone":"",
    "accountBlocked":false,
    "accountCreateTime":1623719604561,
    "lastLoginTime":1625348376450,
    "lastLoginIP":"127.0.0.1",
    "pricePlanId":6,
    "accountExpiresTime":1625953109397,
    "pricePlanTitle":"BASIC1"
    },
  "isError":false
}

If the API call is successful, then the response field “isError” is false. If a numeric field has a value of -1 (minus one), this means “no data” or “unlimited” depending on the context.

getUserAccountInfo

Specific Request Fields:

  • [none]

Specific Error Flags:

  • [none]

getPricePlanInfo

Specific Request Fields:

  • [none]

Specific Error Flags:

  • [none]

JSON Response Example:

{
  "pricePlanInfo":{
    "pricePlanId":6,
    "title":"BASIC1",
    "description":"",
    "isDeprecated":false,
    "lastModified":1625348413042,
    "maxDiskSpaceMB":1024,
    "maxSubUserAccounts":0,
    "maxMeasuringAgentsOwnedByUser":3,
    "maxRemoteProxyRecordersOwnedByUser":3,
    "executeLoadJobsEnabled":true,
    "executeMonitoringJobsEnabled":false,
    "apiAccessEnabled":true,
    "maxStartLoadJobsLast24h":24,
    "maxUsersPerLoadJob":500,
    "maxDurationPerLoadJob":1800
  },
  "isError":false
}

The unit for “maxDurationPerLoadJob” is seconds.

getProjectTree

Specific Request Fields:

  • [none]

Specific Error Flags:

  • [none]

JSON Response Example:

{
  "projectsArray": [
    {
      "projectId": 97,
      "projectName": "Common",
      "projectDescription": "",
      "resourceSetsArray": [
        {
          "resourceSetId": 154,
          "resourceSetName": "Input Files",
          "resourceSetDescription": "",
          "filesArray": [
            {
              "fileName": "InputFile.txt",
              "fileSize": 233,
              "fileHashCode": 1873256029,
              "fileLastModified": 1613835992073
            }
          ]
        },
        {
          "resourceSetId": 155,
          "resourceSetName": "Jar Files",
          "resourceSetDescription": "",
          "filesArray": [
            {
              "fileName": "com.dkfqs.tools.jar",
              "fileSize": 578087,
              "fileHashCode": -2033420926,
              "fileLastModified": 1613838181727
            }
          ]
        },
        {
          "resourceSetId": 156,
          "resourceSetName": "Plug-Ins",
          "resourceSetDescription": "",
          "filesArray": [
            {
              "fileName": "HttpSessionPlugin_ChangeCopyright.json",
              "fileSize": 5321,
              "fileHashCode": 1958407366,
              "fileLastModified": 1613838287871
            }
          ]
        }
      ]
    },
...
...
...
  ],
  "isError": false
}

createProject

Specific Request Fields:

  • projectName
  • projectDescription (optional)

Response Fields:

  • projectId

Specific Error Flags:

  • projectNameError
  • diskSpaceLimitExceededError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"createProject",
  "projectName":"My New Project",
  "projectDescription": "Created by API call"
}

JSON Response Example (Success Case):

{"projectId":113,"isError":false}

JSON Response Example (Error Case):

{"isError":true,"genericErrorText":"","diskSpaceLimitExceededError":false,"projectNameError":true}

deleteProject

Specific Request Fields:

  • projectId
  • moveToTrash (optional, default: false)

Specific Error Flags:

  • projectIdError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"deleteProject",
  "projectId":113,
  "moveToTrash":false
}

getResourceSetsOfProject

Specific Request Fields:

  • projectId

Specific Error Flags:

  • projectIdError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"getResourceSetsOfProject",
  "projectId":97
}

JSON Response Example (Success Case):

{
  "resourceSetsArray": [
    {
      "resourceSetId": 154,
      "resourceSetName": "Input Files",
      "resourceSetDescription": "",
      "filesArray": [
        {
          "fileName": "InputFile.txt",
          "fileSize": 233,
          "fileHashCode": 1873256029,
          "fileLastModified": 1613835992073
        }
      ]
    },
    {
      "resourceSetId": 155,
      "resourceSetName": "Jar Files",
      "resourceSetDescription": "",
      "filesArray": [
        {
          "fileName": "com.dkfqs.tools.jar",
          "fileSize": 578087,
          "fileHashCode": -2033420926,
          "fileLastModified": 1613838181727
        }
      ]
    },
    {
      "resourceSetId": 156,
      "resourceSetName": "Plug-Ins",
      "resourceSetDescription": "",
      "filesArray": [
        {
          "fileName": "HttpSessionPlugin_ChangeCopyright.json",
          "fileSize": 5321,
          "fileHashCode": 1958407366,
          "fileLastModified": 1613838287871
        }
      ]
    }
  ],
  "isError": false
}

createResourceSet

Specific Request Fields:

  • projectId
  • resourceSetName
  • resourceSetDescription (optional)

Response Fields:

  • resourceSetId

Specific Error Flags:

  • projectIdError
  • resourceSetNameError
  • diskSpaceLimitExceededError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"createResourceSet",
  "projectId":97,
  "resourceSetName":"My New Resource Set",
  "resourceSetDescription": "Created by API call"
}

JSON Response Example (Success Case):

{"resourceSetId":172,"isError":false}

JSON Response Example (Error Case):

{"isError":true,"genericErrorText":"","resourceSetNameError":true,"projectIdError":false,"diskSpaceLimitExceededError":false}

deleteResourceSet

Specific Request Fields:

  • projectId
  • resourceSetId
  • moveToTrash (optional, default: false)

Specific Error Flags:

  • projectIdError
  • resourceSetIdError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"deleteResourceSet",
  "projectId":97,
  "resourceSetId":172,
  "moveToTrash":false
}

getFilesInfoOfResourceSet

Specific Request Fields:

  • projectId
  • resourceSetId

Specific Error Flags:

  • projectIdError
  • resourceSetIdError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"getFilesInfoOfResourceSet",
  "projectId":23,
  "resourceSetId":143
}

JSON Response Example:

{
  "filesArray": [
    {
      "fileName": "DKFQSLibrary2.psm1",
      "fileSize": 16339,
      "fileHashCode": -1503445747,
      "fileLastModified": 1603566144851
    },
    {
      "fileName": "powershell-http-bern2.ps1",
      "fileSize": 12900,
      "fileHashCode": -1174212096,
      "fileLastModified": 1603566162094
    },
    {
      "fileName": "TestResult_powershell-http-bern2Neu_2020-10-24@21-06-04.json",
      "fileSize": 14395,
      "fileHashCode": -951574615,
      "fileLastModified": 1603566379097
    },
    {
      "fileName": "TestResult_powershell-http-bern2Neu_2020-10-24@21-09-45.json",
      "fileSize": 55128,
      "fileHashCode": 1499924815,
      "fileLastModified": 1603566591322
    }
  ],
  "isError": false
}

createFile

Specific Request Fields:

  • projectId
  • resourceSetId
  • fileName
  • fileContentB64 (the content of the file, in Base64 format)

Response Fields:

  • fileName
  • fileSize
  • fileHashCode
  • fileLastModified

Specific Error Flags:

  • projectIdError
  • resourceSetIdError
  • fileNameError
  • diskSpaceLimitExceededError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"createFile",
  "projectId":23,
  "resourceSetId":143,
  "fileName":"test.txt",
  "fileContentB64":"VGhpcyBpcyB0aGUgY29udGVudCBvZiB0aGUgZmlsZS4=" 
}

JSON Response Example (Success Case):

{
  "fileName":"test.txt",
  "fileSize":32,
  "fileHashCode":-1460278014,
  "fileLastModified":1625423562384,
  "isError":false
}

JSON Response Example (Error Case):

{"isError":true,"genericErrorText":"","projectIdError":false,"resourceSetIdError":false,"diskSpaceLimitExceededError":false,"fileNameError":true}

getFile

Specific Request Fields:

  • projectId
  • resourceSetId
  • fileName

Response Fields:

  • fileName
  • fileContentB64 (the content of the file, in Base64 format)
  • fileSize
  • fileHashCode
  • fileLastModified

Specific Error Flags:

  • projectIdError
  • resourceSetIdError
  • fileNameError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"getFile",
  "projectId":23,
  "resourceSetId":143,
  "fileName":"test.txt"
}

JSON Response Example (Success Case):

{
  "fileName":"test.txt",
  "fileContentB64":"VGhpcyBpcyB0aGUgY29udGVudCBvZiB0aGUgZmlsZS4=",
  "fileSize":32,
  "fileHashCode":-1460278014,
  "fileLastModified":1625423562384,
  "isError":false
}

deleteFile

Specific Request Fields:

  • projectId
  • resourceSetId
  • fileName
  • moveToTrash (optional, default: false)

Response Fields:

  • fileDeleted (a flag which is true if the file was deleted)

Specific Error Flags:

  • projectIdError
  • resourceSetIdError
  • fileNameError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"deleteFile",
  "projectId":23,
  "resourceSetId":143,
  "fileName":"test.txt",
  "moveToTrash":false
}

JSON Response Example (Success Case):

{"fileDeleted":true,"isError":false}

JSON Response Example (Error Case):

{"isError":true,"genericErrorText":"","projectIdError":false,"resourceSetIdError":false,"fileNameError":true}

getMeasuringAgents

Specific Request Fields:

  • [none]

Response Fields:

  • agentId (the unique measuring agent id)
  • createdBySystem (normally false, true = the user cannot modify or delete the measuring agent)
  • ownerUserId (always the same as the user account id)
  • agentActive (flag: if false then the availability of the measuring agent is not monitored)
  • agentDescription
  • agentHost
  • agentPort
  • authToken (the authentication token to access the measuring agent, or an empty string = no access protection | don’t confuse it with the API authTokenValue)

Specific Error Flags:

  • [none]

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"getMeasuringAgents"
}

JSON Response Example (Success Case):

{
  "measuringAgentsArray": [
    {
      "agentId": 46,
      "createdBySystem": false,
      "ownerUserId": 13,
      "agentActive": true,
      "agentDescription": "Local Agent",
      "agentHost": "127.0.0.1",
      "agentPort": 8080,
      "authToken": "OrKmpkbyNWEHok"
    },
    {
      "agentId": 49,
      "createdBySystem": false,
      "ownerUserId": 13,
      "agentActive": false,
      "agentDescription": "Rasberry 1",
      "agentHost": "192.168.0.51",
      "agentPort": 8080,
      "authToken": ""
    },
    {
      "agentId": 50,
      "createdBySystem": false,
      "ownerUserId": 13,
      "agentActive": true,
      "agentDescription": "Ubuntu 10",
      "agentHost": "192.168.0.110",
      "agentPort": 8080,
      "authToken": ""
    },
    {
      "agentId": 51,
      "createdBySystem": false,
      "ownerUserId": 13,
      "agentActive": true,
      "agentDescription": "Ubuntu 11",
      "agentHost": "192.168.0.111",
      "agentPort": 8080,
      "authToken": ""
    }
  ],
  "isError": false
}

getMinRequiredMeasuringAgentVersion

Specific Request Fields:

  • [none]

Response Fields:

  • minRequiredMeasuringAgentVersion (the minimum required measuring agent version)

Specific Error Flags:

  • [none]

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"getMinRequiredMeasuringAgentVersion"
}

JSON Response Example (Success Case):

{
  "minRequiredMeasuringAgentVersion":"3.9.34",
  "isError":false
}

addMeasuringAgent

Specific Request Fields:

  • agentDescription (must be unique across all measuring agents of the user, cannot be an empty string)
  • agentHost
  • agentPort
  • agentActive (flag: if false then the availability of the measuring agent is not monitored)
  • agentAuthToken (the authentication token to access the measuring agent, or an empty string = no access protection)

Response Fields (JSON object “measuringAgent”):

  • agentId (the unique measuring agent id)
  • createdBySystem (always false for this function)
  • ownerUserId (always the same as the user account id)
  • agentActive (flag: if false then the availability of the measuring agent is not monitored)
  • agentDescription
  • agentHost
  • agentPort
  • authToken (the authentication token to access the measuring agent, or an empty string = no access protection)

Specific Error Flags:

  • agentDescriptionError
  • agentHostError
  • agentPortError
  • maxNumberMeasuringAgentsLimitExceededError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"addMeasuringAgent",
  "agentDescription":"Ubuntu 12",
  "agentHost":"192.168.0.112",
  "agentPort":8080,
  "agentActive": true,
  "agentAuthToken": "nixda"
}

JSON Response Example (Success Case):

{
  "measuringAgent": {
    "agentId": 53,
    "createdBySystem": false,
    "ownerUserId": 13,
    "agentActive": true,
    "agentDescription": "Ubuntu 12",
    "agentHost": "192.168.0.112",
    "agentPort": 8080,
    "authToken": "nixda"
  },
  "isError": false
}

pingMeasuringAgent

Specific Request Fields:

  • agentId

Response Fields (JSON object “agentResponse”):

  • pingFromRemoteIp
  • pingFromRemoteUserId
  • productVersion (measuring agent version | don’t confuse with portal server version)
  • limitMaxUsersPerJob (limit of the measuring agent, -1 = unlimited | don’t confuse with price plan limit)
  • limitMaxJobDurationSeconds (limit of the measuring agent, -1 = unlimited | don’t confuse with price plan limit)
  • osName
  • osVersion
  • javaVersion
  • javaVendor
  • javaMaxMemory
  • systemTime
  • deltaTimeMillis
  • agentStartupTimeStamp
  • httpExecuteTimeMillis

Specific Error Flags:

  • agentIdError
  • agentAccessDeniedError
  • agentVersionOutdatedError
  • agentNotReachableError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"pingMeasuringAgent",
  "agentId":48
}

JSON Response Example (Success Case):

{
  "agentResponse": {
    "pingFromRemoteIp": "83.150.39.44",
    "pingFromRemoteUserId": 13,
    "productVersion": "3.9.30",
    "limitMaxUsersPerJob": 500,
    "limitMaxJobDurationSeconds": 300,
    "osName": "Linux",
    "osVersion": "4.15.0-136-generic",
    "javaVersion": "11.0.1",
    "javaVendor": "Oracle Corporation",
    "javaMaxMemory":"2048 MB",
    "systemTime": 1625513238236,
    "deltaTimeMillis": 841,
    "agentStartupTimeStamp": 1622836702172,
    "httpExecuteTimeMillis": 247
  },
  "isError": false
}

JSON Response Example (Error Case 1):

{
  "isError": true,
  "genericErrorText": "API V1 request to 192.168.0.51:8080 timed out",
  "agentIdError": false,
  "agentAccessDeniedError": false,
  "agentNotReachableError": true,
  "agentVersionOutdatedError": false
}

JSON Response Example (Error Case 2):

{
  "isError": true,
  "genericErrorText": "Min. measuring agent version required: 3.9.30",
  "agentIdError": false,
  "agentAccessDeniedError": false,
  "agentNotReachableError": false,
  "agentVersionOutdatedError": true
}

setMeasuringAgentActive

Specific Request Fields:

  • agentId
  • agentActive

Response Fields:

  • [none]

Specific Error Flags:

  • agentIdError
  • agentAccessDeniedError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"setMeasuringAgentActive",
  "agentId":46,
  "agentActive":false
}

JSON Response Example (Success Case):

{"isError":false}

deleteMeasuringAgent

Specific Request Fields:

  • agentId

Response Fields:

  • [none]

Specific Error Flags:

  • agentIdError
  • agentAccessDeniedError
  • agentDeleteDeniedError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"deleteMeasuringAgent",
  "agentId":54
}

JSON Response Example (Success Case):

{"isError":false}

getMeasuringAgentClusters

Specific Request Fields:

  • [none]

Response Fields (JSON array “measuringAgentClustersArray”):

  • clusterId (the unique cluster id)
  • createdBySystem (normally false, true = the user cannot modify or delete the cluster)
  • ownerUserId (always the same as the user account id)
  • clusterActive (flag: if false then the availability of the cluster is not monitored)
  • clusterDescription
  • controllerHost (the hostname or IP address of the cluster controller)
  • controllerPort (the IP port of the cluster controller)
  • controllerAuthToken (the authentication token to access the cluster controller, or an empty string = no access protection | don’t confuse it with the API authTokenValue)
  • clusterMembersArray
    • clusterMemberId (the unique cluster member id)
    • loadFactor (integer 0..100: the default load factor of this cluster member)
    • agentId (the referenced measuring agent id)
    • agentActive (flag: if false then the availability of the measuring agent is not monitored)
    • agentDescription
    • agentHost
    • agentPort
    • agentAuthToken (the authentication token to access the measuring agent, or an empty string = no access protection | don’t confuse it with the API authTokenValue)

Specific Error Flags:

  • [none]

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"getMeasuringAgentClusters"
}

JSON Response Example:

{
  "measuringAgentClustersArray": [
    {
      "clusterId": 11,
      "createdBySystem": false,
      "ownerUserId": 13,
      "clusterActive": true,
      "clusterDescription": "C1",
      "controllerHost": "192.168.0.50",
      "controllerPort": 8083,
      "controllerAuthToken": "aberaber",
      "clusterMembersArray": [
        {
          "clusterMemberId": 59,
          "loadFactor": 1,
          "agentId": 64,
          "agentActive": true,
          "agentDescription": "Agent 1",
          "agentHost": "192.168.0.10",
          "agentPort": 8080,
          "agentAuthToken": "OrKmAAbyNWEHok"
        },
        {
          "clusterMemberId": 60,
          "loadFactor": 1,
          "agentId": 59,
          "agentActive": true,
          "agentDescription": "Ubuntu 10",
          "agentHost": "192.168.0.110",
          "agentPort": 8080,
          "agentAuthToken": "asc7jhacab"
        },
        {
          "clusterMemberId": 61,
          "loadFactor": 1,
          "agentId": 60,
          "agentActive": true,
          "agentDescription": "Ubuntu 11",
          "agentHost": "192.168.0.111",
          "agentPort": 8080,
          "agentAuthToken": "66ascascsdac"
        }
      ]
    },
    {
      "clusterId": 14,
      "createdBySystem": false,
      "ownerUserId": 13,
      "clusterActive": true,
      "clusterDescription": "C2",
      "controllerHost": "192.168.0.50",
      "controllerPort": 8083,
      "controllerAuthToken": "aberaber",
      "clusterMembersArray": [
        {
          "clusterMemberId": 66,
          "loadFactor": 1,
          "agentId": 56,
          "agentActive": true,
          "agentDescription": "Test System",
          "agentHost": "192.168.0.60",
          "agentPort": 8080,
          "agentAuthToken": "aberdoch"
        },
        {
          "clusterMemberId": 67,
          "loadFactor": 1,
          "agentId": 59,
          "agentActive": true,
          "agentDescription": "Ubuntu 10",
          "agentHost": "192.168.0.110",
          "agentPort": 8080,
          "agentAuthToken": "asc7jhacab"
        }
      ]
    }
  ],
  "isError": false
}

getClusterControllers

Specific Request Fields:

  • [none]

Response Fields (JSON array “clusterControllersArray”):

  • controllerHost (the hostname or IP address of the cluster controller)
  • controllerPort (the IP port of the cluster controller)
  • controllerAuthToken (the authentication token to access the cluster controller)
  • measuringAgentClustersArray (an array of measuring agent clusters which are referencing this cluster controller)
    • clusterId
    • clusterDescription
    • clusterActive

Specific Error Flags:

  • [none]

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"getClusterControllers"
}

JSON Response Example:

{
  "clusterControllersArray": [
    {
      "controllerHost": "192.168.0.33",
      "controllerPort": 8083,
      "controllerAuthToken": "2fasdtfffe",
      "measuringAgentClustersArray": [
        {
          "clusterId": 11,
          "clusterDescription": "C1",
          "clusterActive": 1
        },
        {
          "clusterId": 13,
          "clusterDescription": "C2",
          "clusterActive": 1
        },
        {
          "clusterId": 14,
          "clusterDescription": "C3",
          "clusterActive": 1
        }
      ]
    },
    {
      "controllerHost": "192.168.0.50",
      "controllerPort": 8083,
      "controllerAuthToken": "asfsdgh763",
      "measuringAgentClustersArray": [
        {
          "clusterId": 15,
          "clusterDescription": "C4",
          "clusterActive": 1
        },
        {
          "clusterId": 16,
          "clusterDescription": "C7",
          "clusterActive": 1
        }
      ]
    }
  ],
  "isError": false
}

getMinRequiredClusterControllerVersion

Specific Request Fields:

  • [none]

Response Fields:

  • minRequiredClusterControllerVersion (the minimum required cluster controller version)

Specific Error Flags:

  • [none]

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"getMinRequiredClusterControllerVersion"
}

JSON Response Example:

{
  "minRequiredClusterControllerVersion":"4.0.4",
  "isError":false
}

pingClusterController

Specific Request Fields:

  • controllerHost (the cluster controller host name or IP address)
  • controllerPort (the cluster controller IP port)
  • controllerAuthToken (the authentication token to access the cluster controller, or an empty string = no access protection)

Response Fields (JSON object “controllerResponse”):

  • pingFromRemoteIp
  • pingFromRemoteUserId
  • productVersion (cluster controller version | don’t confuse with portal server version)
  • osName
  • osVersion
  • javaVersion
  • javaVendor
  • javaMaxMemory
  • systemTime
  • deltaTimeMillis
  • controllerStartupTimeStamp
  • httpExecuteTimeMillis
  • clusterControllerOutdated

Specific Error Flags:

  • controllerHostError
  • controllerPortError
  • controllerVersionOutdatedError
  • controllerNotReachableError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"pingClusterController",
    "controllerHost":"192.168.0.50",
    "controllerPort":8083,
    "controllerAuthToken":"hagsajjs99"
}

JSON Response Example (Success Case):

{
  "controllerResponse": {
    "pingFromRemoteIp": "192.168.0.100",
    "pingFromRemoteUserId": 13,
    "productVersion": "4.0.4",
    "osName": "Linux",
    "osVersion": "4.15.0-135-generic",
    "javaVersion": "11.0.1",
    "javaVendor": "Oracle Corporation",
    "javaMaxMemory": "512 MB",
    "systemTime": 1643406118552,
    "deltaTimeMillis": 1120,
    "controllerStartupTimeStamp": 1643322597013,
    "httpExecuteTimeMillis": 249,
    "clusterControllerOutdated": false
  },
  "isError": false
}

JSON Response Example (Error Case 1):

{
  "isError": true,
  "genericErrorText": "API call pingGetControllerInfo failed. Error code = 18, Error message = Invalid authentication token",
  "controllerHostError": false,
  "controllerVersionOutdatedError": false,
  "controllerNotReachableError": true,
  "controllerPortError": false
}

JSON Response Example (Error Case 2):

{
  "isError": true,
  "genericErrorText": "Min. cluster controller version required: 4.0.4",
  "controllerHostError": false,
  "controllerVersionOutdatedError": true,
  "controllerNotReachableError": false,
  "controllerPortError": false
}

addMeasuringAgentCluster

Specific Request Fields:

  • clusterActive (flag: if false then the availability of the cluster is not monitored)
  • clusterDescription (must be unique across all measuring agent clusters and all measuring agents of the user, cannot be an empty string)
  • controllerHost (the cluster controller host name or IP address)
  • controllerPort (the cluster controller IP port)
  • controllerAuthToken (the authentication token to access the cluster controller, or an empty string = no access protection)
  • clusterMembersArray (an array of cluster members - can also be empty)
    • agentId (the referenced measuring agent id)
    • loadFactor (integer 0..100: the load factor of this cluster member, recommended value = 1)

Response Fields:

  • clusterId (the unique cluster id)
  • clusterMembersArray (the array of cluster members)
    • clusterMemberId (the unique cluster member id)
    • agentId (the referenced measuring agent id)
    • loadFactor (integer 0..100: the load factor of this cluster member)

Specific Error Flags:

  • clusterDescriptionError
  • controllerHostError
  • controllerPortError
  • agentIdError
  • loadFactorError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"addMeasuringAgentCluster",
  "clusterActive":true,
  "clusterDescription":"C7",
  "controllerHost":"192.168.0.50",
  "controllerPort":8083,
  "controllerAuthToken":"aberaber",
  "clusterMembersArray":[
    {
      "agentId":59,
      "loadFactor":1
    },
    {
      "agentId":60,
      "loadFactor":1
    }
  ]
}

JSON Response Example (Success Case):

{
  "clusterId":16,
  "clusterMembersArray":[
    {
      "clusterMemberId":71,
      "agentId":59,
      "loadFactor":1
    },
    {
      "clusterMemberId":72,
      "agentId":60,
      "loadFactor":1
    }
  ],
  "isError":false
}

JSON Response Example (Error Case):

{
  "isError": true,
  "genericErrorText": "Invalid agentId = 101",
  "controllerHostError": false,
  "agentIdError": true,
  "controllerPortError": false,
  "loadFactorError": false,
  "clusterDescriptionError": false
}

addMemberToMeasuringAgentCluster

Specific Request Fields:

  • clusterId
  • agentId (the referenced measuring agent id)
  • loadFactor (integer 0..100: the load factor of this cluster member, recommended value = 1)

Response Fields (JSON object “clusterMember”):

  • clusterMemberId (the unique cluster member id)
  • agentId
  • loadFactor

Specific Error Flags:

  • clusterIdError
  • clusterAccessDeniedError
  • clusterModifyDeniedError
  • agentIdError
  • agentAccessDeniedError
  • loadFactorError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"addMemberToMeasuringAgentCluster",
  "clusterId":17,
  "agentId":64,
  "loadFactor":1
}

JSON Response Example:

{
  "clusterMember": {
    "clusterMemberId": 75,
    "agentId": 64,
    "loadFactor": 1
  },
  "isError": false
}

removeMemberFromMeasuringAgentCluster

Specific Request Fields:

  • clusterId
  • clusterMemberId

Response Fields:

  • [none]

Specific Error Flags:

  • clusterIdError
  • clusterAccessDeniedError
  • clusterModifyDeniedError
  • clusterMemberIdError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"removeMemberFromMeasuringAgentCluster",
  "clusterId":17,
  "clusterMemberId":75
}

JSON Response Example:

{"isError":false}

pingMeasuringAgentClusterMembers

Specific Request Fields:

  • clusterId

Response Fields (JSON object “controllerResponse”):

  • productVersion (cluster controller version)
  • clusterConnectResult (the connect information to the cluster members)
    • measuringAgentClusterMemberArray (the array of cluster members)
      • clusterMemberId
      • loadFactor
      • agentId
      • agentActive
      • agentDescription
      • agentHost
      • agentPort
      • agentAuthToken
    • connectSuccessfulClusterMemberArray (the array of cluster member ids to which the connection was successful established)
    • connectFailedClusterMemberArray (the array of cluster members to which the connection has failed)
      • clusterMemberId
      • errorMessage
    • clusterConnectStartTimestamp
    • clusterConnectDurationMillis
  • clusterActionResult (the ping result of the cluster members)
    • actionSuccessfulClusterMemberArray (the array of cluster member ids which have performed the ping to the measuring agent)
    • actionFailedClusterMemberArray (the array of cluster members which have not performed the ping to the measuring agent)
      • clusterMemberId
      • errorMessage
    • jsonResponseClusterMemberArray (the array of cluster member which have performed the ping)
      • clusterMemberId
      • jsonResponseObject (the pong response of the cluster member)
        • productVersion (measuring agent product version)
        • systemTime
        • deltaTimeMillis (the OS time difference in milliseconds between the cluster controller and the measuring agent)
        • osName
        • osVersion
        • javaVersion
        • javaVendor
        • javaMaxMemory
        • samplingGranularityMillis (the data collector sampling granularity in milliseconds)
        • isError (boolean flag, normally always false)
        • measuringAgentOutdated (a boolean flag, true = measuring agent product version is outdated)
    • clusterActionStartTimestamp
    • clusterActionDurationMillis
  • httpExecuteTimeMillis
  • clusterControllerOutdated

Specific Error Flags:

  • clusterIdError
  • clusterAccessDeniedError
  • controllerVersionOutdatedError
  • controllerNotReachableError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"pingMeasuringAgentClusterMembers",
  "clusterId":16
}

JSON Response Example (Success Case):

{
  "controllerResponse": {
    "productVersion": "4.0.4",
    "clusterConnectResult": {
      "measuringAgentClusterMemberArray": [
        {
          "clusterMemberId": 71,
          "loadFactor": 1,
          "agentId": 59,
          "agentActive": true,
          "agentDescription": "Ubuntu 10",
          "agentHost": "192.168.0.110",
          "agentPort": 8080,
          "agentAuthToken": "agsdhagsj"
        },
        {
          "clusterMemberId": 72,
          "loadFactor": 1,
          "agentId": 60,
          "agentActive": true,
          "agentDescription": "Ubuntu 11",
          "agentHost": "192.168.0.111",
          "agentPort": 8080,
          "agentAuthToken": "nvbjnvbnn"
        }
      ],
      "connectSuccessfulClusterMemberArray": [
        71,
        72
      ],
      "connectFailedClusterMemberArray": [],
      "clusterConnectStartTimestamp": 1643410829270,
      "clusterConnectDurationMillis": 79
    },
    "clusterActionResult": {
      "actionSuccessfulClusterMemberArray": [
        71,
        72
      ],
      "actionFailedClusterMemberArray": [],
      "jsonResponseClusterMemberArray": [
        {
          "clusterMemberId": 71,
          "jsonResponseObject": {
            "productVersion": "4.0.4",
            "systemTime": 1643410829340,
            "deltaTimeMillis": -10,
            "osName": "Linux",
            "osVersion": "5.4.0-92-generic",
            "javaVersion": "11.0.1",
            "javaVendor": "Oracle Corporation",
            "javaMaxMemory": "2048 MB",
            "samplingGranularityMillis": 4000,
            "isError": false,
            "measuringAgentOutdated": false
          }
        },
        {
          "clusterMemberId": 72,
          "jsonResponseObject": {
            "productVersion": "4.0.4",
            "systemTime": 1643410829351,
            "deltaTimeMillis": -10,
            "osName": "Linux",
            "osVersion": "5.4.0-92-generic",
            "javaVersion": "11.0.1",
            "javaVendor": "Oracle Corporation",
            "javaMaxMemory": "2048 MB",
            "samplingGranularityMillis": 4000,
            "isError": false,
            "measuringAgentOutdated": false
          }
        }
      ],
      "clusterActionStartTimestamp": 1643410829349,
      "clusterActionDurationMillis": 43
    },
    "httpExecuteTimeMillis": 1778,
    "clusterControllerOutdated": false
  },
  "isError": false
}

JSON Response Example (Error Case / Partly failed):

{
  "controllerResponse": {
    "productVersion": "4.0.4",
    "clusterConnectResult": {
      "measuringAgentClusterMemberArray": [
        {
          "clusterMemberId": 71,
          "loadFactor": 1,
          "agentId": 59,
          "agentActive": true,
          "agentDescription": "Ubuntu 10",
          "agentHost": "192.168.0.110",
          "agentPort": 8080,
          "agentAuthToken": "marderzahn"
        },
        {
          "clusterMemberId": 72,
          "loadFactor": 1,
          "agentId": 60,
          "agentActive": true,
          "agentDescription": "Ubuntu 11",
          "agentHost": "192.168.0.111",
          "agentPort": 8080,
          "agentAuthToken": "marderzahn"
        }
      ],
      "connectSuccessfulClusterMemberArray": [
        72
      ],
      "connectFailedClusterMemberArray": [
        {
          "clusterMemberId": 71,
          "errorMessage": "Connection refused (Connection refused)"
        }
      ],
      "clusterConnectStartTimestamp": 1643414272214,
      "clusterConnectDurationMillis": 97
    },
    "clusterActionResult": {
      "actionSuccessfulClusterMemberArray": [
        72
      ],
      "actionFailedClusterMemberArray": [],
      "jsonResponseClusterMemberArray": [
        {
          "clusterMemberId": 72,
          "jsonResponseObject": {
            "productVersion": "4.0.4",
            "systemTime": 1643414272310,
            "deltaTimeMillis": -8,
            "osName": "Linux",
            "osVersion": "5.4.0-92-generic",
            "javaVersion": "11.0.1",
            "javaVendor": "Oracle Corporation",
            "javaMaxMemory": "2048 MB",
            "samplingGranularityMillis": 4000,
            "isError": false,
            "measuringAgentOutdated": false
          }
        }
      ],
      "clusterActionStartTimestamp": 1643414272311,
      "clusterActionDurationMillis": 21
    },
    "httpExecuteTimeMillis": 1769,
    "clusterControllerOutdated": false
  }
}

setMeasuringAgentClusterActive

Specific Request Fields:

  • clusterId
  • clusterActive

Response Fields:

  • [none]

Specific Error Flags:

  • clusterIdError
  • clusterAccessDeniedError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"setMeasuringAgentClusterActive",
  "clusterId":16,
  "clusterActive":true
}

JSON Response Example (Success Case):

{"isError":false}

deleteMeasuringAgentCluster

Specific Request Fields:

  • clusterId

Response Fields:

  • [none]

Specific Error Flags:

  • clusterIdError
  • clusterAccessDeniedError
  • clusterDeleteDeniedError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"deleteMeasuringAgentCluster",
  "clusterId":16
}

JSON Response Example (Success Case):

{"isError":false}

getProxyRecorders

Specific Request Fields:

  • [none]

Response Fields (JSON array “proxyRecordersArray”):

  • recorderId (the unique proxy recorder id)
  • createdBySystem (normally false, true = the user cannot modify or delete the proxy recorder)
  • ownerUserId (always the same as the user account id)
  • recorderDescription
  • recorderProxyHost
  • recorderProxyPort (HTTP and HTTPS port of the proxy)
  • recorderProxyAuthUsername (proxy authentication username, or an empty string = no proxy authentication required)
  • recorderProxyAuthPassword (proxy authentication password)
  • recorderControlPort (the proxy recorder control port)
  • recorderControlAuthToken (the authentication token to access the proxy recorder control port, or an empty string = no access protection | don’t confuse it with the API authTokenValue)

Specific Error Flags:

  • [none]

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"getProxyRecorders"
}

JSON Response Example:

{
  "proxyRecordersArray": [
    {
      "recorderId": 3,
      "createdBySystem": false,
      "ownerUserId": 13,
      "recorderDescription": "Erster",
      "recorderProxyHost": "192.168.0.40",
      "recorderProxyPort": 8082,
      "recorderProxyAuthUsername": "",
      "recorderProxyAuthPassword": "",
      "recorderControlPort": 8081,
      "recorderControlAuthToken": ""
    },
    {
      "recorderId": 4,
      "createdBySystem": false,
      "ownerUserId": 13,
      "recorderDescription": "proxy.realload.com",
      "recorderProxyHost": "proxy.realload.com",
      "recorderProxyPort": 8082,
      "recorderProxyAuthUsername": "max.meier",
      "recorderProxyAuthPassword": "123456",
      "recorderControlPort": 8081,
      "recorderControlAuthToken": "aZujkl97zuwert"
    }
  ],
  "isError": false
}

getMinRequiredProxyRecorderVersion

Specific Request Fields:

  • [none]

Response Fields:

  • minRequiredProxyRecorderVersion (the minimum required HTTP/S proxy recorder version)

Specific Error Flags:

  • [none]

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"getMinRequiredProxyRecorderVersion"
}

JSON Response Example (Success Case):

{
  "minRequiredProxyRecorderVersion":"0.2.2",
  "isError":false
}

addProxyRecorder

Specific Request Fields:

  • recorderDescription (must be unique across all HTTP/S proxy recorders of the user, cannot be an empty string)
  • recorderProxyHost
  • recorderProxyPort (HTTP and HTTPS port of the proxy)
  • recorderProxyAuthUsername (proxy authentication username, or an empty string = no proxy authentication required)
  • recorderProxyAuthPassword (proxy authentication password, applied if recorderProxyAuthUsername is not an empty string)
  • recorderControlPort (the proxy recorder control port)
  • recorderControlAuthToken (the authentication token to access the proxy recorder control port, or an empty string = no access protection)

Response Fields (JSON object “proxyRecorder”):

  • recorderId (the unique HTTP/S proxy recorder id)
  • createdBySystem (always false for this function)
  • ownerUserId (always the same as the user account id)
  • recorderDescription
  • recorderProxyHost
  • recorderProxyPort
  • recorderProxyAuthUsername
  • recorderProxyAuthPassword
  • recorderControlPort
  • recorderControlAuthToken

Specific Error Flags:

  • recorderDescriptionError
  • recorderProxyHostError
  • recorderProxyPortError
  • recorderControlPortError
  • maxNumberProxyRecordersLimitExceededError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"addProxyRecorder",
  "recorderDescription":"My New Proxy Recorder",
  "recorderProxyHost":"192.168.0.148",
  "recorderProxyPort":8082,
  "recorderProxyAuthUsername":"max.meier",
  "recorderProxyAuthPassword":"123456",
  "recorderControlPort":8081,
  "recorderControlAuthToken":"aZujkl97zuwert"
}

JSON Response Example (Success Case):

{
  "proxyRecorder": {
    "recorderId": 10,
    "createdBySystem": false,
    "ownerUserId": 13,
    "recorderDescription": "My New Proxy Recorder",
    "recorderProxyHost": "192.168.0.148",
    "recorderProxyPort": 8082,
    "recorderProxyAuthUsername": "max.meier",
    "recorderProxyAuthPassword": "123456",
    "recorderControlPort": 8081,
    "recorderControlAuthToken": "aZujkl97zuwert"
  },
  "isError": false
}

pingProxyRecorder

Specific Request Fields:

  • recorderId

Response Fields (JSON object “pongResponse”):

  • pingFromRemoteIp
  • pingFromRemoteUserId
  • productVersion (the remote proxy recorder version | don’t confuse with portal server version)
  • recorderComponentVersion (the proxy recorder component version | don’t confuse with portal server version)
  • isRecording
  • recordHostFilter
  • numRecordedElements
  • osName
  • osVersion
  • javaMemoryMB
  • javaVersion
  • javaVendor
  • systemTime
  • deltaTimeMillis
  • httpExecuteTimeMillis

Specific Error Flags:

  • recorderIdError
  • recorderAccessDeniedError
  • recorderNotReachableError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"pingProxyRecorder",
  "recorderId":4
}

JSON Response Example (Success Case):

{
  "pongResponse": {
    "pingFromRemoteIp": "83.150.39.44",
    "pingFromRemoteUserId": 13,
    "productVersion": "0.2.0",
    "recorderComponentVersion": "1.1.0",
    "isRecording": false,
    "recordHostFilter": "www.dkfqa.com",
    "numRecordedElements": 0,
    "osName": "Linux",
    "osVersion": "5.4.0-74-generic",
    "javaMemoryMB": 2048,
    "javaVersion": "11.0.1",
    "javaVendor": "Oracle Corporation",
    "systemTime": 1625529858405,
    "deltaTimeMillis": 790,
    "httpExecuteTimeMillis": 88
  },
  "isError": false
}

JSON Response Example (Error Case):

{
  "isError": true,
  "genericErrorText": "connect timed out",
  "recorderNotReachableError": true,
  "recorderIdError": false,
  "recorderAccessDeniedError": false
}

deleteProxyRecorder

Specific Request Fields:

  • recorderId

Response Fields:

  • [none]

Specific Error Flags:

  • recorderIdError
  • recorderAccessDeniedError
  • recorderDeleteDeniedError

JSON Request Example:

{
  "authTokenValue":"jPmFClqeDUXaEk8Q274q",
  "action":"deleteProxyRecorder",
  "recorderId":10
}

JSON Response Example (Success Case):

{"isError":false}