REST API integration

A number of REST APIs have been developed for easier integration with core BMC ProactiveNet constructs. These REST APIs are important for integrating with BMC ProactiveNet, and this document explains the best practices for consuming the REST APIs. See BMC ProactiveNet web services concepts to get a good understanding of the best practices for consuming REST APIs, and how to use them.

Best Practices for writing REST clients

There are various ways of consuming the REST APIs. For the purpose of getting to know these APIs, use the Firefox browser plugin called Poster or HttpClient to see the sample input or output. However, for integrating BMC ProactiveNet with other components, ensure that the APIs are consumed programmatically.

Sample client code

You can write a REST client using languages such as C, Java, Ruby, and Python, and you can use many third party software for this purpose. In this document, we will use Java-based REST client. The following steps describe how to write a sample code that connects to REST API using Apache's Common httpclient.

1. Create an instance of the HTTP method you want to call (For example, GET, POST, PUT, DELETE)

           GetMethod getMethod = new GetMethod(url);

2. Create an instance of the HTTP client

            HttpClient client = new HttpClient();

3. Add an authentication header (this header will display a generated value)

            getMethod.addRequestHeader("authorization" , "authtoken TC9r9c/izIOdaQzztOjlqDE8ozc=");

4. Execute the method

int status =client.executeMethod(getMethod);           
InputStream stream = getMethod.getResponseBodyAsStream();

5. Process the response

6. Close the connection

getMethod.releaseConnection();

Sample client utility

BMC ProactiveNet has a sample Java-based REST client that is located in the pw\restclient folder. You can run this command from the command line. You can also copy this folder to use the client independently. To run this client, ensure that you set the classpath using the provided scripts. After setting the classpath, execute the APIs using the command line. Ensure that you have the URL and the username/password credentials before running the client.

For detailed information about the sample client, see Utilities for web services.

Authentication

All REST APIs are required to be authenticated for successful operation. You can authenticate the REST APIs in the following ways:

URL encoded format

In this type, a successful authentication log in REST API generates an authentication token. Use this authentication token for all subsequent REST APIs. By default, the authentication token expires after twenty four hours. However, you can configure the expiry time.

The syntax of authentication log in a POST API is:

http(s)://serverHost:port/bppmws/api/authenticate/login

With this, you should supply the the user name and password in URL-encoded format. After successful authorization, the API responds with the authentication token. Use this authentication token in the header of subsequent web services calls. For example:

authorization authtoken TC9r9c/izIOdaQzztOjlqDE8ozc=

Base 64 encoded format

To generate this token, a concatenated string of the user name and password separated by a colon (:) is encoded in the Base 64 format. A web service client uses this encoded string as the user credentials in the HTTP header. Every web service request must have the Base 64-encoded format of the user credentials in the HTTP header. For example:

authorization basic YWRtaW46YWRtaW4=

For detailed information about the authentication, see Web services authentication.

Best Practices for authentication

• For better security, BMC recommends that you use the authtoken generated through the URL encoded format. The validity of the token is limited. Authtoken is a more secure and efficient way of authentication, especially for a typical REST interaction between solutions that involve multiple invocations over time.
• If you know that your REST interactions are over, BMC recommends that you make an explicit log-out call to invalidate the token.
• The basic authorization is effective for one-off purposes. BMC recommends that you use HTTPS while doing basic authentication.

Identifying the target resource for the REST APIs

The identifier used for specifying the REST API target are of the following types:

• ReconID - for BMC Atrium CMDB-based references. Most efficient look-up. This is same as CI_ID.
• URI - unique resource identifier for the resource type. Efficient look-up.
• IPAddress - applicable to computer systems.
• Name - applicable in general, assumes external enforcement of uniqueness.

Best Practices for identifying the target resource for the REST APIs

BMC recommends that you use the above order of the types of IDs. That is, a ReconID (applicable to a CI resource) is the ID type to use if you are dealing with CI targets and you know the appropriate reconID. A URI is the next best ID type and is generally applicable to most target resource types including CI, device, and so on. This reduces the chances of finding duplicate resources. Any other identifier for devices is subject to contention and may result in BMC ProactiveNet response similar to Non-Unique identifier found.

For details about the format of the URI, see URI format for a resource.

Guidelines for performance APIs

BMC ProactiveNet REST-based web service APIs can be used to retrieve metadata, config data, and statistical data for specific BMC ProactiveNet- monitored resources.

To retrieve performance data, ensure that you use the meta or config APIs to retrieve the handles (monitor types, attributes, monitor instances) and use the latter to extract the appropriate metrics through stats calls.

The statistical data (metrics) for BMC ProactiveNet monitored resources can be retrieved using the following options:

1. Use of Metadata API

Call the metadata API to get the monitor name and attribute names (GET)

        http://<bppm-server>:<port>/bppmws/api/Device/vw-pun-ngp-dv27/metadata?idType=Name

Use the monitor name and attribute name information in the stats API to get the performance data for that resource (GET)

        http://<bppm-server>:<port>/bppmws/api/Device/resourceName/stats?idType=Name&monitor=CPU:CPU_UTILIZATION

2. Use of config data API 

Call the configdata API to get the monitorInstance ID, and monitor name and attribute names (GET)

        http://<bppm-server>:<port>/bppmws/api/Device/resourceID/configdata?idType=CI_ID

Use the monitorInstance id (vw-pun-ngp-dv27:21003:2) and monitor, attribute names (CPU:CPU_UTILIZATION) to the performance data for that resource (GET)

        http://<bppm-server>:<port>/bppmws/api/MonitorInstance/vw-pun-ngp-dv27:21003:2/stats?monitor=CPU:CPU_UTILIZATION

For detailed information about the performance APIs, see Retrieving data from BMC ProactiveNet.

Difference between Meta API and Config API

The meta API call yields higher level information that you can use for retrieving stats for all instances of a type or device. The config API call lets you be very specific with regards to retrieving metrics only for targeted monitor instances.

Guidelines for event-based APIs

Event-based APIs allow you to create and modify CI or device-associated events.

To create an event, you  use the POST API, and ensure that the body contains all the information that is necessary to create an event. To associate the event with the device or CI, you must provide an idType to identify the resource. The supported idTypes are Name, RECON_ID, and URI. For example:

http(s)://serverHost:port/bppmws/api/resourceType/resourceID/event?idType=IDType&subType=subType

subType is used to further distinguish the type of device that is referenced. Supported values are, CLUSTER, PHYSICAL_SERVER, VIRTUAL_MACHINE, VIRTUAL_HOST, VIRTUAL_INFORMATION_MANAGER, and RESOURCE_POOL. For example, to associate events with a cluster called vcenter, use the subType CLUSTER. The parameter subType is not applicable for the CI resourceType.

Best Practices for Event-based API

The JSON body of the API has the information to create and associate the event to the correct resource. To associate the event with the specified resource, ensure that either the mc_smc_id parameter of the event has the same value as that of the mc_udid parameter of the resource, or that the mc_smc_alias parameter of the event has the same value as that of the componentAlias parameter of the resource.
For more information about integration input parameters, see the Example use case scenarios to manage events.

Guidelines for CI-based APIs

In BMC ProactiveNet version 9.0, there are various APIs that manage and retrieve CIs. APIs cover the Create, Read, Update, and Delete functionality of the  CIs.

Best Practices for for Search CI and CI Details APIs

Typically, the consumption of CI-based APIs start from finding the CIs that are available. You can Find CIs in a system in the following ways:

1. Simple search using GET API. Here, you can find CIs based on Name, CI_ID/RECON_ID, URI. There are some filtering options available based on CLASS or PriorityWatchdog. The search provides a list of CIs that match the criteria ascending by Name.

http://<bppm-server>:<port>/bppmws/api/CI/Name_of_the_CI/search?idType=Name 

2. A more elaborate and configurable version of finding CIs can be achieved using the POST API of search. This API takes the search criteria as input. This criteria can have any conditions on which search should take place. Use the BMC ProactiveNet- provided utility called JSON Creator to create a search criteria. This utility is available at pw\restclient.http://<bppm-server>:<port>/bppmws/api/CI/search.
The search APIs support pagination with the parameter - page. To fetch contents from the second page, specify page=2. Otherwise, only the CIs from the first page are fetched by default.
The output of the search gives multiple attributes of the CI. For more details, see Managing configuration items.

http://<bppm-server>:<port>/bppmws/api/CI/ID_of_the_CI/details 

The query parameter filter in the details API can be used to filter the response limited to the parameter supplied.For example, if you specify filter=status, the response will contain regular information such as ID and status.

Best Practices for creating and updating CI-based web services

When specifying the JSON, ensure that the slot names are in proper case. Based on the Child server on which you need to create CIs, provide the correct routing information. If routing information is not provided, the CIs will be created on the same server where the web service request is targeted. Ensure that information for mandatory slots is provided.

For detailed information about CI-based APIs, see Managing configuration items.

Error Codes from web services

The web services follow the REST standard, and it also conforms to the HTTP error code format. The error code from the web service is in the HTTP header, and also in the message itself. In general, the numbering of the error codes is derived from the HTTP error code format. For example, 200 represents OK, 404 represents Not found and so on. We have also used an HTTP error code of 203 to denote the partial response. In a multi-server environment, when a call to the web service fails on one of the servers but succeeds on other servers, the web services return the HTTP error code as 203.

The body of the message also has more detailed error code such as BPPM-RWS50000E meaning an internal server error occurred. Contact your administrator if you see such an error.

For detailed information about error codes, see Getting started with BMC ProactiveNet web services.