CloudTest Server Management API

Introduction

The Server Management API is a REST API that allows technical support, engineers, and users to gather information about a running server to assist in problem analysis. In particular it is used to assist in diagnosing memory issues. At it’s most basic level it can return general information about servers inluding their name, id’s and which services they are running.

The following API end points are available:

  • info: Get information about a single server.

Authentication

For more information, see the Tokens API.

To use the REST APIs, callers must issue a request using the CloudTest URL below to get a security token. Note that the CloudTest API URL is case sensitive.

To get a security token with a username and password:

curl -X PUT -H "Content-type: application/json" --data-binary '{"userName":"<username>", "password":"xxxxx"}' "https://[host name]/concerto/services/rest/RepositoryService/v1/Tokens"

If Single Sign On (SSO) is enabled for the default tenant of the user, an apiToken must be specified instead:

curl -X PUT -H "Content-type: application/json" --data-binary '{"apiToken":"<token>"}' "https://[host name]/concerto/services/rest/RepositoryService/v1/Tokens"

Users who belong to multiple tenants and wish to obtain a security token for a tenant that is not their default, can add the “tenant” key to the JSON body:

curl -X PUT -H "Content-type: application/json" --data-binary '{"apiToken":"<token>", "tenant": "<tenant>"}' "https://[host]/concerto/services/rest/RepositoryService/v1/Tokens"

The REST JSON response will contain the security token needed for further calls: {"token":"da7be4d72030656559f3e41a98924a6b2a544730"}

Once a security token is acquired, it is used in all subsequent queries. The URLs for accessing the REST API use the token, the server id, and any optional parameters that go with the end point, and take the following format:

/concerto/services/rest/servermanagement/v1/<id>/info?<optional parameters>

If curl is used, the command line looks like this:

curl -H "Authentication: <security token>" "https://[host name]/services/rest/servermanagement/v1/info?<optional parameters>"

Errors

Error Code Meaning
400 Bad Request – Input Error
401 Unauthorized – The Authorization Token is invalid
404 Not Found – The specified resource could not be found
405 Method Not Allowed – Invalid method used to access resource
429 Too many Requests – too many requests were sent within a short amount of time, for the same tenant
500 Internal Server Error – The request caused a server error.

Server Management

Getting a list of enabled servers can be retrieved using the url below.

/concerto/services/rest/servermanagement/v1

If the server ID is known, then summary information about that server can be obtained like this:

/concerto/services/rest/servermanagement/v1/<id>/info

URL Query Parameters

Parameter Description
detailedStatus ‘true’ to get detailed memory information (Results Service only)

Example URLs

To get the list of servers along with their ids:

GET /concerto/services/rest/servermanagement/v1

To get information about the server with ID 42:

GET /concerto/services/rest/servermanagement/v1/42/info

To get memory use details for the results server with id 42:

GET /concerto/services/rest/servermanagement/v1/42/info?detailedStatus=true

Request

curl -X GET -H "X-Auth-Token: 1234-ABC" -H "Content-Type: application/json" http://[host name]/concerto/services/rest/servermanagement/v1/42/info

Response

{
  "id": 1,
  "location": "Virginia Location 1",
  "server": "Main Results Database",
  "enabled": true,
  "verified": true,
  "services": [
    {
      "service": "results",
      "settings": {
        "HealthCheck.Database.Max.Problem.Percent": "5",
        "Writer.MinimumDBDiskSpaceWarning": "2000"
      },
      "type": "Writer"
    }]}