Client REST interface

The AppMon Client can request information about configured servers and manage some AppMon Server features through a REST interface. This REST service can be configured in the Client Preferences dialog box.

The following examples use the default port setting, port 8030.

Note

The Client REST interface is not available over the network. For security reasons, only requests from localhost are allowed. The functionality that uses the interface must reside on the same machine as the AppMon Client. For access across machines, you can use the Server REST Interfaces.

Note

The AppMon Client REST interface is bound to a TCP port. If multiple AppMon Clients are running on the same physical machine and all AppMon Clients are using the same port (the default port), the REST interface can run for only one AppMon Client. If the AppMon Client is started within a terminal server session, the REST interface might not start because the port is being used by another AppMon Client within another session.

Parameters

Most of the services require parameters to be executed. Depending on the service and its use cases, different parameter types are used.

Type Description Example
Path Path parameters are templates that are part of the URI. http://localhost:8030/rest/management/profiles//startrecording
Query A query string parameter represents one part of the URI's query string. http://localhost:8030/rest/management/profiles.xml?server=myserver
Form A parameter in the body of an HTTP POST request with the MIME type application/x-www-form-urlencoded. HTML form using HTTP POST:
<form method="POST" action="http://localhost:8030/rest/management/profiles/easyTravel/startrecording">
  Server Name:
  <input type="text" name="server" value="myserver" />
  <input type="submit" value="Start Recording" />
</form>

Available interfaces

These services are provided through the Client REST interface:

Request client version

This service returns the version of the AppMon Client. You can specify an extension (.xml, .json, or .jsonp) to request the version in your preferred representation.

HTTP Method URI Content Type
GET http://localhost:8030/rest/management/version application/xml
GET http://localhost:8030/rest/management/version.xml application/xml
GET http://localhost:8030/rest/management/version.json application/json
GET http://localhost:8030/rest/management/version.jsonp application/javascript

### List Server Connections {#anchor_list-server-connections} This service returns a list of Servers currently configured in the AppMon Client. Servers not currently connected are included in the list.

HTTP Method URI Content Type
GET http://localhost:8030/rest/management/servers application/xml
GET http://localhost:8030/rest/management/servers.xml application/xml
GET http://localhost:8030/rest/management/servers.json application/json
GET http://localhost:8030/rest/management/servers.jsonp application/javascript

List System Profiles

The AppMon Client has interfaces to list configured System Profiles of all connected AppMon Servers or to limit the list by specifing the alias of an AppMon Server. The content type of the response can be specified by an extension: .xml, .json, or .jsonp.

HTTP Method URI Content Type
GET http://localhost:8030/rest/management/profiles application/xml
GET http://localhost:8030/rest/management/profiles.xml application/xml
GET http://localhost:8030/rest/management/profiles.json application/json
GET http://localhost:8030/rest/management/profiles.jsonp application/javascript

Session recording

Start session recording

This service starts session recording for a specified profile on an AppMon Server and returns the recording session ID. If recording is already active for this session, the ID of the recording session is returned.

HTTP Method URI Content Type
POST http://localhost:8030/rest/management/profiles/{PROFILENAME}/startrecording application/x-www-form-urlencoded

Stop session recording

This service stops session recording for a specified System Profile on an AppMon Server. If no recording is currently active, nothing happens.

HTTP Method URI Content Type
POST http://localhost:8030/rest/management/profiles/{PROFILENAME}/stoprecording application/x-www-form-urlencoded

List recording sessions

This service returns a list of all stored sessions that are currently recording at the AppMon Server with name SERVERALIAS:

HTTP Method URI Content Type
GET http://localhost:8030/rest/management/recordingsessions/{SERVERALIAS}/ application/xml

If a System Profile is specified by the optional query string parameter, only the corresponding System Profile is checked for recording sessions.

Tasks

AppMon provides some built-in tasks such as session recording that can be configured to run at a certain time. See Tasks for more details.

Session recording task

Using this interface, you can schedule a session recording task on an AppMon Server. If a session recording task with the same task name already exists, the settings of the existing task are overwritten. In contrast to Start Session Recording, the session recording task can be scheduled to run in the future and recording stops.

If session recording is already running, the task cannot be executed.

The user must have permissions for session recording, and read and write permissions for the System Profile.

Specify the start time, according to a subset of ISO 8601, by the pattern yyyy-MM-dd'T'HH:mm:ss (For example 2012-02-22T14:05:00). The time parameters are based on the local time of the AppMon Client.

HTTP Method URI Content Type
GET http://localhost:8030/rest/integration/tasks/sessionrecording application/xml
GET http://localhost:8030/rest/integration/tasks/sessionrecording.xml application/xml
GET http://localhost:8030/rest/integration/tasks/sessionrecording.json application/json
GET http://localhost:8030/rest/integration/tasks/sessionrecording.jsonp application/javascript

Cancel a task

Using this interface, you can stop a running task or cancel a scheduled task. A running session recording task is stopped immediately.

HTTP Method URI Content Type
GET http://localhost:8030/rest/integration/tasks/cancel application/xml
GET http://localhost:8030/rest/integration/tasks/cancel.xml application/xml
GET http://localhost:8030/rest/integration/tasks/cancel.json application/json
GET http://localhost:8030/rest/integration/tasks/cancel.jsonp application/javascript

Drilldown to AppMon

Open PurePath

This interface allows external systems to reference single PurePaths that are known to the AppMon Server. It opens specified PurePaths in the AppMon Client.

HTTP Method URI Content Type
GET http://localhost:8030/rest/integration/openpurepath text/xml
POST http://localhost:8030/rest/integration/openpurepathlist text/xml

PurePath Identifier Format

Various REST services use the following notation for specifying a PurePath:

PA=<Agent>;PT=<Tag>[;RS=<Session>|;SP=<SystemProfile>][;PS=<Server>]
Part Description Mandatory Example
PA The Agent tag in decimal or hex (starting with '0x') format. yes PA=0x4ae37f41
PT The tag number in decimal format. yes PT=0
RS The stored session name. no RS=easyTravel/20111202140852_0.session
SP The system profile name. no SP=easyTravel
PS If specified, must be the decimal Server ID for the Server that knows about the PurePaths. no PS=-219389494

This format is mostly used by automated integration tools that determine the ID values from some other source. If you need to retrieve the values for a specific PurePath, you can open the PurePath dashlet and choose Details on the specific PurePath. The Agent ID and Tag ID is listed there.

If RS= is omitted or the denoted stored session cannot be found, OpenPurePath Services tries to open the PurePath from the live session.

If PS= is omitted, the AppMon Server is automatically determined. If the AppMon Server is specified but the identification is wrong, no PurePath opens.

Open PurePath Services shows selected PurePaths in a built-in dashboard. It is possible to open several PurePaths from different sessions. For every session, a separate dashboard is opened. To uniquely identify the dashboards, the name of the System Profile is prepended to the dashboard name. For example, for PurePaths from easyTravel and AjaxWorld live sessions, two dashboards are opened:

  • easyTravel PurePaths contains all PurePaths from the easyTravel live session.
  • AjaxWorld PurePaths contains all PurePaths from the AjaxWorld live session.

If the dashboardname parameter is specified, behavior depends on whether a dashboard with that name (case-insensitive) is already open in the AppMon Client. If it is already open, that dashboard is copied.

Using the previous example:

  • easyTravel <dashboardname> contains all PurePaths from the easyTravel live session.
  • AjaxWorld <dashboardname> contains all PurePaths from the AjaxWorld live session.

If a dashboard with that name is not currently open, the built-in dashboard is used, resulting in the same dashboard names, but with content equal to the first example.

If a specific unique dashboard such as easyTravel PurePaths is already open, that dashboard is updated according to the source and PurePath filters, and is activated again. Dashlet-specific source and filters (PurePath and TimeFrame) are discarded in the new dashboard.

Open dashboard

The Open Dashboard interface allows external systems to open specific dashboards in the AppMon Client. Through this service, a built-in dashboard can be opened and its data source, compare source, and filters can be configured. If a dashboard with the specified name is already open, this dashboard is reused; the data source, compare source, and filters are reset to the new parameters. If no built-in dashboard is found for the given name, a default integration dashboard is opened and renamed.

HTTP Method URI Content Type
GET http://localhost:8030/rest/integration/opendashboard application/xml

Deprecated interfaces

As AppMon is continually improving the Client REST services, some legacy interfaces get replaced by more powerful ones. This means that legacy interfaces are currently working, but might be removed in an upcoming release. it is recommend that you not use interfaces that are marked as deprecated. This section describes all deprecated interfaces and links to the services that should be used instead.

JSON/JSONP Server Connection list

This interface returns a list of configured servers as JSON data. Additionally, the field hostServerRestrictionEnabled outlines whether the AppMon Client starts using Webstart. The AppMon Client is only allowed to connect to its host server (the AppMon Server it was downloaded from).

Request type HTTP GET
URI localhost:8030/rest/management/servers-json

List System Profiles of server

This service shows a list of profile names that are configured at the specified AppMon Server. The server name must be part of the URI.

Request type HTTP GET Content Type
URI localhost:8030/rest/management/profiles/SERVERNAME application/xml

Generate Reports

This feature is deprecated

In earlier releases, the REST Webservice interfaces were available as part of the AppMon Client. As of Release 3.5, the REST interfaces and the schedules are executed on the AppMon Server. The REST interfaces of the AppMon Client are still available for backwards compatibility. However, scripts using REST web services should switch the port used to the Server-side REST Webservice port and adjust the REST interface usage, because the Client-side interfaces might be removed in future versions. See Server REST Interfaces for details.

The AppMon Client offers a REST interface to generate reports locally. The request response is a line of text specifying the full path to the generated report.

Request type HTTP GET
URI http://localhost:8030/rest/management/report/REPORTTYPE?dashboardname=DASHBOARDNAME

The report type (REPORTTYPE) must be included in the request URL. The type value can be one of the following:

  • XML ‐ An XML report document. See also XML Reporting (REST).
  • PDF ‐ A PDF report document.
  • HTML ‐ An HTML document.
  • CSV ‐ A CSV report.

The dashboard name (DASHBOARDNAME) can optionally be submitted as a query string parameter. It specifies the name of the dashboard to report. If no dashboard name is specified, the active dashboard on the AppMon Client is reported.

Consider the fundamental differences among the export formats: HTML, PDF, XLS (rich text and graphics), XML (data and metadata), and CSV (delimited data with column titles). These formats are described in detail in the Reporting page.

HTTP Responses

  • 200 ‐ OK: The request successfully executed.
  • 403 ‐ Forbidden: The request was legal but the user is not allowed to create this report.
  • 404 ‐ Not Found: A matching dashboard or a valid Server connection could not be found.
  • 500 ‐ Internal Server Error: See HTTP body for information.

Examples