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.
  • 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.

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

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.


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*