Deleting hosts with a REST API

Use this endpoint to delete one or more existing hosts.

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:

Related topics

API for creating hosts

API for enabling or disabling Agents

API for modifying user groups associated with hosts

API for modifying tag details associated with hosts

Endpoint overview

Use the DELETE method to delete one or more existing hosts.

While running this request, at a minimum you need to specify the name or ID of the host that you want to delete. You can delete multiple hosts by specifying a comma-separated list of host names or host IDs. You can obtain the host ID by running the API for listing host details.

While deleting the hosts, you can also delete the data collectors associated with the host and the data collected by those data collectors.

In a scenario where you have duplicate host names associated with unique Agent names (Collection Station or Collection Agent), you can delete the host by specifying one of the following inputs:

Unique ID of the host (instead of the host name).
Name of the Agent associated with the host.

Note that while you can specify multiple host names for deleting, you cannot specify multiple Agent names to identify unique hosts for deleting.

Request URL

DELETE <protocol>://<host>:<port>/olaengine/itdaws/hostservices/hosts/<hostDetails>?agentName=<agentName>&delColl=<operation>&delData=<operation>&type=<identifierType>&version=<apiVersion>

Parameter definitions

The following parameters can be used in the request URL.

Parameter name Description

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

Required

Details of the hosts that you want to delete.

Depending on the value of the type parameter, the value can be one of the following:

Host name: Host name appearing on the Administration > Hosts page.
Host ID: Unique ID associated with the host; can be obtained by running the endpoint for listing host details.

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

type

Optional, default is name

Type of identifier that must be used as the criterion for deleting hosts.

Can be one of the following:

name: Set this value if you plan to specify host names.
id: Set this value if you plan to specify host IDs.

delColl

Optional, default is false

Indicates whether you want to delete the data collectors associated with the host.

Can be one of the following:

true
false

delData

Optional, default is false

Indicates whether you want to delete the data collected by the data collectors associated with the host.

Can be one of the following:

true
false

agentName

Optional

Indicates the name of the Collection Station or Collection Agent associated with the host.

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 deleting hosts by using the DELETE method.

Example 1: Delete a single host
Example 2: Delete multiple hosts
Example 3: Delete hosts with duplicate names (by specifying the Agent name)

Example 1: Delete a single host

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

Delete a single host, "HostA" on the "localhost" machine.
Delete the data collector associated with the host.
Delete the data collected using the data collector.

Request URL

DELETE http://localhost:9797/olaengine/itdaws/hostservices/hosts/HostA

Response

{
    "statusCode": "200",
    "statusMessage": "OK",
    "hosts": [{
        "messages": [{
            "text": "SUCCESS"
        }, {
            "code": "Sucessfully Deleted Host Id: 4fc3a6d2-3df0-448d-883a-59d6b7d15338 . Host Name: HostA"
        }]
    }],
    "totalRecords": 1,
    "pageSize": 0
}

Example 2: Delete multiple hosts

The following example illustrates the input and response for deleting multiple hosts by specifying the host names, "HostB" and "HostC" on the "localhost" machine:

Request URL

DELETE http://clm-pun-015982:9797/olaengine/itdaws/hostservices/hosts/HostB,HostC?type=name

Response

{
	"statusCode": "200",
	"statusMessage": "OK",
	"hosts": [{
		"messages": [{
			"text": "SUCCESS"
		}, {
			"code": "Sucessfully Deleted Host Id: 82070460-44aa-4869-9308-2aac92be6d47 . Host Name: HostB"
		}]
	}, {
		"messages": [{
			"text": "SUCCESS"
		}, {
			"code": "Sucessfully Deleted Host Id: 3f5bb10a-95ae-4878-84e9-e674823bb9f4 . Host Name: HostC"
		}]
	}],
	"totalRecords": 2,
	"pageSize": 0
}

Example 3: Delete hosts with duplicate names (by specifying the Agent name)

The following example illustrates the input and response for deleting a duplicate host name, "HostD" along with its associated data collector, by specifying the Agent name, "Agent1.bmc.com".

Request URL

DELETE http://localhost:9797/olaengine/itdaws/hostservices/hosts/HostD?agentName=Agent1.bmc.com&delColl=true&type=name

Response

{
    "statusCode": "200",
    "statusMessage": "OK",
    "hosts": [{
        "messages": [{
            "text": "SUCCESS"
        }, {
            "code": "Sucessfully Deleted Host Id: 68513608-ffb1-4539-b823-710236c6c401 . Host Name: HostD"
        }]
    }],
    "totalRecords": 1,
    "pageSize": 0
}

Response elements

The following sections help you understand the response elements:

Element definitions
Successful response sample
Unsuccessful response sample
Multiple status response sample

Element definitions

The endpoint response contains the following main elements:

Response element	Description
`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 deleted. The parameters in the array have one-to-one mapping with the inputs specified in the request body. Unsuccessful response: Details of the error – severity, error code, and error message. Multiple status response: Based on the success or failure of multiple independent operations, the array can contain successful responses (hosts deleted) and unsuccessful responses (error details).
`totalRecords` Long	The total number of hosts deleted by running the API.
`pageSize` Long	By default, the value displayed is zero.

Successful response sample

See examples.

Unsuccessful response sample

{
    "statusCode": "400",
    "statusMessage": "Bad Request",
    "hosts": [{
        "messages": [{
            "severity": "Error",
            "code": "entity.does.not.exist",
            "text": "Invalid Host Name. Host Name with value host6 does not exist."
        }]
    }],
    "totalRecords": 1,
    "pageSize": 0
}

Multiple status response sample

{
    "statusCode": "207",
    "statusMessage": "Multi Status",
    "hosts": [{
        "messages": [{
            "severity": "Error",
            "code": "entity.does.not.exist",
            "text": "Invalid Host Name. Host Name with value HostB does not exist."
        }]
    }, {
        "messages": [{
            "text": "SUCCESS"
        }, {
            "code": "Sucessfully Deleted Host Id: 75d067f6-ad83-465e-8587-25bae915fbd2 . Host Name: HostA"
        }]
    }],
    "totalRecords": 2,
    "pageSize": 0
}

HTTP status codes

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

Status code	Description
200	Request completed successfully.
207	Some hosts could not be deleted.
400	Invalid inputs: Host name does not exist. Host is associated with multiple Agents. Host is assigned to a data collector. Host is not associated with the specified Agent.
401	Authorization error (invalid authorization token or authorization token not present).
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.

Deleting hosts with a REST API

Endpoint overview

Request URL

Parameter definitions

Examples

Example 1: Delete a single host

Example 2: Delete multiple hosts

Example 3: Delete hosts with duplicate names (by specifying the Agent name)

Response elements

Element definitions

Successful response sample

Unsuccessful response sample

Multiple status response sample

HTTP status codes

Comments