Server REST interfaces

The AppMon Server and AppMon Client expose management and integration functionality using REST interfaces. Through these interfaces, you can start and stop session recording, trigger memory and thread dumps, create reports, and other tasks.

REST interface access

You can access all AppMon Server REST interfaces with HTTP 1.1 and HTTPS 1.1 using the default ports of 8020 and 8021. Most interfaces are accessible at https://<YourDTServerHost>:8021/api-docs/current/. Here you can execute them, and find the description.

See Set up Communication Connections for information on how to change port setting and how to enable or disable the REST interfaces.

Find the description of the REST services in the right-hand side-bar.

REST interface documentation

The REST interfaces reference documentation is based on the Swagger specification and accessible on the AppMon Server. By default, an interactive rendering of the documentation is accessible at https://<YourDTServerHost>:8021/api-docs/current/. While much of this documentation is reproduced here for evaluation purposes, the REST interface documentation on the AppMon Server is the most current.

HTTP response codes

The HTTP status response code shows your request result. The RFC 2616 standard (W3C, IETF) describes the status codes.

For example, if the request was successfully received, understood, and accepted, the REST interface returns a status code of class 2xx. If the request could not be understood by the AppMon Server, a status code of class 4xx is returned. A status code from class 5xx indicates that a server error prevented the AppMon Server from completing the request.

The following are common response codes:

  • 200: OK: The request has succeeded.
  • 201: Created: The request was fulfilled and resulted in a new resource being created.
  • 202: Accepted: The request was accepted for processing, but the processing has not been completed.
  • 204: No Content: The request has succeeded but does not have an entity-body in the response.
  • 400: Bad Request: Some request parameters are not correct.
  • 401: Unauthorized: A valid authorization header (Basic Authentication) is required but is not available.
  • 403: Forbidden: Request execution is not allowed, for example because the user has no privileges.
  • 404: Not Found: Some entities could not be found, such as System Profile, Dashboard, Collector, or Agent.
  • 500: Internal Server Error: See response body for details.
  • 501: Not Implemented: The requested service is currently not implemented.

Authentication and authorization

Most AppMon REST interfaces sections require authentication. All pages and services requiring authentication are by default only available if HTTPS is used. This default setting can be changed in Webserver Management, but is not recommended. Configure the HTTPS certificates in Certificate Management.

The User Agent must authenticate itself using HTTP Basic Authentication to access AppMon REST interfaces. RFC 2617 describes this authentication technique. The BASE 64 hash key must be calculated based on the concatenated string consisting of the user name, a colon (:), and the password. The string Basic plus the hash key must be set as the Authorization header to the HTTP request. See the Wikipedia page for more information.

Once successfully authenticated, the AppMon Server checks authorization to access the REST interfaces. If there is no Web Service Interface Access permission, the HTTP status code 401 (Unauthorized) is returned. Depending on the requested service, the additional permissions may be needed, for example to access a certain dashboard or System Profile.

Transferring your username and password is only secure, if you use HTTPS. Disabling the HTTP port within Webserver Management or selecting the option to Accept authentication data only with HTTPS is recommended.