Listing host details with a REST API
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
- Example 2: List details of all the hosts containing the particular name specified
- Example 3: List details of multiple hosts with associated tags
- Example 4: List details of all the tags associated with the existing hosts
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
"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
"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
"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
"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
The endpoint response contains the following main elements:
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.