Listing host details with a REST API

Use this endpoint to list details of particular hosts or all the hosts existing in the system.

Notes

  • Before running this endpoint, you need to generate an authorization token by running the login endpoint. This token is used to authenticate a user into the product. You need to pass this token in the header each time you want to run the endpoint.
  • If the check.csrf.header.XRequestedWith header property in the olaengineConfig.properties file is set to TRUE, then you need a new header 
    X-Requested-With=XMLHttpRequest to be added to the API calls. For accessing the application in secure mode (from CSRF), the addition of this header is mandatory in every request.

  • To log out from a given session, you need to run the logout endpoint.

For more information, see Developing.

This topic contains the following information:

Endpoint overview

Use the GET method to list details of multiple hosts or all the hosts existing in the system.

You can get details of hosts by specifying the specific host names. To specify multiple values, you need to specify a comma-separated list of host names. The host names specified as the input need not be exact names. You can also specify a portion of the host name to get details of all the hosts matching that portion fully and partially. Suppose you have three hosts containing "CLM" in the name, by specifying "CLM", you can list details of all the three hosts.

A full or partial host name input matches any of the host names containing that input. For example, the input, "itda-host" returns details of host names, "itda-host", "itda-host-clm", "Hou-itda-host".

The specified input returns zero or more matching results. Suppose you specify the input, "itda,pun". If the existing host names only contain the name "itda" and not "pun", details of the hosts containing "itda" in their names are returned.

When you run this endpoint, the response contains the following details:

  • Basic details about the host, such as the name, instance name, and ID.
  • Details about the associated Agent, such as the name, ID, and status (enabled or disabled).
  • Details about the associated user groups, such as the name and ID
  • Total count of available records (hosts).
  • Page size – if set, the configured value is displayed, otherwise 0 is displayed.

You can customize the response by applying pagination, determined by the pageNumber and pageSize parameters. You can also include details regarding the tags associated with the hosts by specifying the field=tags parameter.

Request URL

GET <protocol>://<host>:<port>/olaengine/itdaws/hostservices/hosts?host=<hostDetails>&field=tags&pageNumber=<pageIndex>&pageSize=<countOfRecords>&version=<apiVersion>

Parameter definitions

The following parameters can be used in the request URL.

Parameter nameDescription

<protocol>

Required

Protocol that you want to use for communication with the Console Server.

Can be one of the following:

  • http
  • https

<host>

Required

Host name of the Console Server.

<port>

Required

Port number of the Console Server.

The default port is 9797.

<hostDetails>

Optional

Names of the hosts for which you want to get details.

To specify multiple hosts, specify a comma-separated list of host names.

You can even specify a list of partial names to match all the hosts containing that name.

field=tags

Optional

Includes details regarding the tags associated with the hosts in the response.

When specified, details regarding the Agents and user groups associated with the hosts is not provided in the response.

pageNumber

Optional, default is 1

Page number from which you want to list host details.

pageSize

Optional, default is 100

Maximum number of records to be presented in a page.

This parameter can be used to customize the API response only and has no effect on the UI.

version

Optional

Version of the API.

You can specify the version as 2.5.

Tip: Generally the API version is the same as the product version on which the API can be run.

Examples

The following examples illustrate the inputs for getting host details by using the GET method.

Example 1: List details of all the hosts

The following example illustrates the input and response for listing details of all the hosts existing in the system.

Request URL

GET http://localhost:9797/olaengine/itdaws/hostservices/hosts

Response
{
    "statusCode": "200",
    "statusMessage": "OK",
    "hosts": [{
        "host": {
            "id": "ae9890d7-40c1-4ca5-82bd-e58b81ada358",
            "name": "HostB-CLM-Pun",
            "instanceName": "HostB-CLM-Pun",
            "agents": [{
                "agentId": "Agent1.bmc.com",
                "agentName": "Agent1.bmc.com",
                "enabled": true
            }],
            "userGroupList": [{
                "userGroupId": "cb5d776a-0831-4a20-a3f5-37b7a7d043c3",
                "userGroupName": "TroubleshooterGroup",
                "deletable": null,
                "organizationID": null,
                "users": null
            }]
        }
    }, {
        "host": {
            "id": "c08a31dc-a63a-44d1-9351-4c42af663cc3",
            "name": "ITDAColl",
            "instanceName": "ITDAColl",
            "agents": [{
                "agentId": "collection-station_hou.bmc.com",
                "agentName": "collection-station_hou.bmc.com",
                "enabled": true
            }],
            "tagsList": {
                "os": ["Linux", "Windows"]
            }
        }
    }, {
        "host": {
            "id": "d67953aa-5c93-443a-a826-c24af725050c",
            "name": "CLM-Houston",
            "instanceName": "CLM-Houston",
            "agents": [{
                "agentId": "collection-station_hou.bmc.com",
                "agentName": "collection-station_hou.bmc.com",
                "enabled": true
            }]
        }
    }],
    "totalRecords": 3,
    "pageSize": 0
}

Example 2: List details of all the hosts containing the particular name specified

The following example illustrates the input and response for performing the following actions:

  • List details of all the hosts containing "clm" in their names.
  • Return details from page number 1 with a page size of not more than 2 records.
Request URL

GET http://localhost:9797/olaengine/itdaws/hostservices/hosts?host=clm&pageSize=2&pageNumber=1

Response
{
    "statusCode": "200",
    "statusMessage": "OK",
    "hosts": [{
        "host": {
            "id": "ae9890d7-40c1-4ca5-82bd-e58b81ada358",
            "name": "HostB-CLM-Pun",
            "instanceName": "HostB-CLM-Pun",
            "agents": [{
                "agentId": "Agent1.bmc.com",
                "agentName": "Agent1.bmc.com",
                "enabled": true
            }],
            "userGroupList": [{
                "userGroupId": "cb5d776a-0831-4a20-a3f5-37b7a7d043c3",
                "userGroupName": "TroubleshooterGroup",
                "deletable": null,
                "organizationID": null,
                "users": null
            }]
        }
    }, {
        "host": {
            "id": "d67953aa-5c93-443a-a826-c24af725050c",
            "name": "CLM-Houston",
            "instanceName": "CLM-Houston",
            "agents": [{
                "agentId": "collection-station_hou.bmc.com",
                "agentName": "collection-station_hou.bmc.com",
                "enabled": true
            }]
        }
    }],
    "totalRecords": 3,
    "pageSize": 2
}

Example 3: List details of multiple hosts with associated tags

The following example illustrates the input and response for listing details of all the hosts containing the names, "ITDAColl" or "CLM-Houston" and listing details of the associated tags.

Request URL

GET http://localhost:9797/olaengine/itdaws/hostservices/hosts?host=ITDAColl,CLM-Houston&field=tags

Response
{
    "statusCode": "200",
    "statusMessage": "Ok",
    "hosts": [{
        "host": {
            "id": "42ee353e-51eb-4408-8849-9edf38fbdb50",
            "name": "ITDAColl",
            "tagsList": {
                "ApplicationContext": ["ITDA"],
                "os": ["Windows"],
                "location": ["Houston"]
            }
        }
    }, {
        "host": {
            "id": "7d0a0703-44a3-4421-a021-b8c1564f7ea2",
            "name": "CLM-Houston",
            "tagsList": {
                "os": ["Windows"]
            }
        }
    }],
    "totalRecords": 4,
    "pageSize": 100
}

Example 4: List details of all the tags associated with the existing hosts

The following example illustrates the input and response for listing details of all the tags associated with the hosts (listed on page 1) with the page size set to 2.

Request URL
GET http://localhost:9797/olaengine/itdaws/hostservices/hosts?field=tags&pageSize=2
Response
{
    "statusCode": "200",
    "statusMessage": "Ok",
    "hosts": [{
        "host": {
            "id": "30a6d190-40b7-4025-aff4-612e8faa68c1",
            "name": "HostA",
            "tagsList": {
                "": [null]
            }
        }
    }, {
        "host": {
            "id": "42ee353e-51eb-4408-8849-9edf38fbdb50",
            "name": "VW-PUN-INC-QA44.dsl.bmc.com",
            "tagsList": {
                "os": ["Windows"],
                "location": ["Houston"]
            }
        }
    }],
    "totalRecords": 4,
    "pageSize": 2
}

Response elements

The following sections help you understand the response elements:

Element definitions

Response elementDescription

statusCode

String

A string describing the status code returned.

For more information, see HTTP status codes.

statusMessage 

String

Message explaining the reason for the response.

hosts

Array

Can be one of the following:
  • Successful response: Details of one or more hosts created.
    The parameters in the array have one-to-one mapping with the inputs specified in the request body.
  • Unsuccessful response: Nil

totalRecords

Long

The total number of host records present in the system.

pageSize

Long

Can be one of the following:

  • The default page size (100).
  • The page size input provided while running the API request.

Successful response sample

See examples.

Unsuccessful response sample

{
    "statusCode": "404",
    "statusMessage": " No Host Found with the given criteria",
    "hosts": [],
    "totalRecords": 3,
    "pageSize": 0
}

HTTP status codes

The following table describes the status codes that are likely to appear while working with this endpoint.

Status codeDescription
200Request completed successfully.
401Authorization error (invalid authorization token or authorization token not present).
404No host was found for the specified criteria.
500

Error occurred while processing the request. Occurrence of this error is rare.

For more information, see the error message. Alternatively, see the itda.log located at %BMC_ITDA_HOME%\logs.


Was this page helpful? Yes No Submitting... Thank you

Comments