IBM Business Monitor REST Interface

IBM Business Monitor provides a set of APIs that are implemented using Representational State Transfer (REST) Services. The URIs are a set of REST services that access Monitor data. For a direct link to all resources and methods, see the quick summary.

Introduction

The Representational State Transfer (REST) APIs are public APIs that you can use to extract monitor data or to create custom dashboards and reports based on monitor data. The REST implementation allows for easy to use HTTP services that are language- and platform-independent, stateless, scalable, and easily parsed. The REST APIs are extremely useful for creating AJAX-style web applications, in the same vein as the Monitor dashboards.

REST Services provide a set of Uniform Resource Identifiers (URIs) that allow you to interact with Monitor resources such as monitoring context definitions, key performance indicators (KPIs), and instance data. The services can be invoked by any HTTP client application, and define an expected response in the form of a JavaScript Object Notation (JSON) object. The JSON format can be easily parsed and consumed by JavaScript and other products, tools, and languages, which allows you greater flexibility in leveraging in your own environment.

Many of the services take a simple HTTP GET URI as input. More complicated services take a JSON input via HTTP GET(for retrieval), POST(for create) or PUT(for update). Results are typically returned in JSON, with the exception of services that are naturally XML-based, such as the diagram service, which returns an SVG XML document. Any error messages and status indicators are returned in the HTTP response as JSON output.

Resource URLs

The format of each WBM REST resource URI is as follows:

http://{host}:{port}/rest/bpm/monitor/{service URI}?{query}

where:

"http://{host}:{port}" contains the host address and port
"/rest/bpm/monitor" is the context root.
"/{service URI}?{query}" represents the logical resource

Resource Versioning

The following changes are considered compatible between versions and must be expected by clients:

Adding new REST resource relationship to the resource model, without affecting existing navigation
Adding additive information to REST representations that won't affect existing clients
Adding a new MIME type / representation support
Adding new properties to existing JSON objects returned to a client (ignored by backlevel clients)
Adding new properties to existing JSON objects received from a client (defined as optional)

HTTP Methods

The WBM REST interface provides the following HTTP methods ([RFC 2616]):

POST - create a resource
GET - read a resource
PUT - update a resource
DELETE - delete a resource

Content Types

The data sent or returned by the HTTP methods listed above has one of the following content types ([RFC 2045][RFC 2046]):

JSON ("Content-Type: application/json") is used for most WBM resources; for the detailed format of each returned object, see JSON Schema ([JSON Schema]) specifications for each individual operation
XML ("Content-Type: text/xml") is used as return data type for diagrams, export measure data, export instance data, etc.
Form ("Content-Type: application/x-www-form-urlencoded") is used for HTTP request inputs. Instance export uses this content type as the request input type. For other REST services, this content type can also be used as long as the payload is sent under the form parameter "input".

Using HTTP Content-Type in REST requests

When a client sends an HTTP request with payload, normally the HTTP content-type header should be set to describe the payload format. If no content type is set, the HTTP request content type is set to the default value, application/x-www-form-urlencoded. The default content type is not set by the Business Monitor server , but by the browser if the client is a browser or dashboard. If using a Java test program, the default content type is set by the HTTPRequest class. Monitor 6.1 and 6.1.1 tolerated clients that failed to set the content type. Now, Websphere Business Monitor supports HTTP Form POST (Content-Type: application/x-www-form-urlencoded). Therefore, clients must be explicit and set either application/json or application/x-www-form-urlencoded, depending on whether clients are sending a JSON payload directly in the HTTP request body or a form payload. When sending a form payload, JSON data must be embedded in the form and passed to the REST service using an input form parameter set to the JSON string and a content_type form parameter set to application/json.

To access the URIs, enter the following Web address in your browser: http://monitor_server:monitor_server_port/rest/bpm/monitor/REST_URI.

Where:

monitor_server is the host name of the Business Monitor server

monitor_server_port is the port where the REST servlet is running

REST_URI is the actual URI of the REST service

Error Handling

For errors recognized during processing of a WBM REST request, an appropriate HTTP status code ([RFC 2616]) is returned to the calling client (e.g., 200 OK or 404 Not Found, see the individual operations for details). Additional error information is provided depending on the error type. For WBM exceptions, the corresponding WBM error number and error message is returned. For severe errors (HTTP status code 500 Internal Server Error), additional programmer’s details are returned. They can be propagated to IBM service personnel if required.

Security Considerations

Some firewalls do not allow HTTP PUT/DELETE traffic to traverse the firewall, as it is considered dangerous for regular web content that may not be properly secured. As a workaround, PUT and DELETE requests can be 'tunneled' through a POST using the "X-Method-Override" or "X-HTTP-Method-Override" HTTP headers. The two headers are synonymous, so we should check for "the alias if the first isn't present.

References

The following specifications provide additional helpful information:

Subtopics

The following subtopics describe the resource sets defined for this product:

Model

These services return metadata about deployed monitor models. The single-version services return metadata specific to a single model version; whereas the cross-version services return a union of all objects that have been defined across all model versions.
Diagram

These services return Scalable Vector Graphics (SVG) diagrams for deployed monitor models. An SVG diagram is specific to a single monitor model version; however, the KPIs annotated on a diagram may be calculated using instances from multiple monitor model versions.
Monitoring Context Instance Data

This is a set of REST interfaces that return to the end user information in regard to monitoring context instances.
Cube

These services return metadata about cube dimensions and measures and Alphablox cube status.
Alert

These services support the retrieval and management of alert subscriptions and alerts.
KPI

These services support the retrieval and management of Key Performance Indicators (KPIs). KPIs are specific to a single model version; however, the KPI value may be calculated using instances from multiple monitor model versions.
Business Situation

This is a set of REST interfaces that allow for listing, creating, updating, and deleting Business Situation Alerts.

Modeled business situation alerts are situations that are created based on the monitor model definitions that exist at the time of deployment. These alert definitions are created using the WebSphere administration console. A modeled alert only be subscribed to using REST services.

Dynamic business situation alerts are situations that are created based on both monitor model KPI definitions that exist at the time of deployment and KPI definitions created dynamically after deployment. Dynamic alert definitions are created using these REST interfaces. A dynamic alert may be both configured and subscribed to using REST services and will not be displayed in the WebSphere administration console.