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.

Available interfaces

Authentication and authorization

AppMon REST interfaces sections require authentication. All pages and services requiring authentication are by default only available via HTTPS. You can enable HTTP at the Management tab of the Services item from the Dynatrace Server Settings dialog box, but is not recommended. You may need to configure the HTTPS certificates.

HTTP Basic Authentication is used 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 for permission to access the REST interfaces. If the authenticated user doesn't have the 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. We recommend to disable the HTTP port within t the Management tab of the Services item from the Dynatrace Server Settings dialog box, or activate the Accept authentication data only with HTTPS option.

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.

Built-in 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/. All of the documentation is reproduced here—just select the required interface above or in the left-hand navigation.

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.

Cross-origin resource sharing (CORS)

AppMon 2018 October

This feature is available in the AppMon 2018 October release only.

Due to browser security restrictions, the REST API cannot usually be called from scripts embedded into an external website. To allow this external integration, CORS needs to be activated on the AppMon Server. This is done by setting the allowed origins via the debug flag com.dynatrace.diagnostics.webservices.cors.allowedOrigins. For the specified origins, the HTTP methods GET, PUT, POST, DELETE and HEAD will be allowed. To restrict the allowed methods, this list can be overridden by setting the debug flag com.dynatrace.diagnostics.webservices.cors.allowedMethods. All request headers will be accepted by default, restrictions can be applied by specifying the allowed list of headers by setting the debug flag com.dynatrace.diagnostics.webservices.cors.allowedHeaders. The changed debug flags will be in effect once the embedded web server has been restarted. This can be done in the server services setting page by disabling and re-enabling the web server and clicking apply in between.