Announcing the Dynatrace API explorer & OpenAPI specification

It’s been some time since Dynatrace was announced as a new member of the OpenAPI specification consortium. Since then, we’ve worked hard to enhance each of our Dynatrace API endpoints by providing a formal and machine processable OAS specification. The OpenAPI Specification (OAS) is a specification for machine-readable interface files that are used to describe, produce, consume, and visualize RESTful web services. There are a variety of tools available that can generate code, documentation, and test cases based on a given interface file.

One major enhancement that accompanies a machine-readable API specification is the generation of an API explorer. Typically, API explorers allow you to review all existing endpoints and directly try out those endpoints.

Because an OAS specification is now automatically included for each Dynatrace REST endpoint, you’re assured that all recent changes are automatically reflected within the new Dynatrace API explorer.

There are numerous use cases for OAS specifications beyond the generation of an API explorer. Popular use cases for OAS specifications include:

• Automatic generation of API documentation and an API explorer
• Automatic check for new endpoints and deprecations
• Automatic generation of language bindings (for example, Python, Go, Java, and .NET)
• Automatic generation of API tests

Dynatrace API explorer

Once you’ve learned what an API specification provides, it’s time to review the benefits of the newly introduced Dynatrace API explorer.

To access the Dynatrace API explorer

1. From the navigation menu, select Settings > Integrations > Dynatrace API.
2. Click the Dynatrace API explorer link at the top of the page.
   

The Dynatrace API explorer lists all available API endpoints for the given Dynatrace environment. You’ll recognize the traditional API endpoints for pulling time-series or topological information from your monitored environment. Just below the title, you’ll find a link to the raw OAS specification, which can be used with any OAS-compatible tool (for example, Swagger).

Global unlock of API endpoints

When you open one of the given API endpoints, a dialog appears with information about the API tokens that secure the endpoint you’ve selected. Each endpoint demands a specific type of token. By clicking the global Authorize button (see callout in the example below), you can see which token scopes are necessary for all API endpoints.

By entering your personal API token into the global Available authorizations dialog, you unlock all related API endpoints. Once you’ve entered your API token, you can directly execute API calls within the API explorer. The Dynatrace API call example below retrieves the cluster release version. A click on the Try it out button (not shown) opens the parameter section of the selected API endpoint, where you can enter additional parameters and modify the request payload before executing it by clicking the Execute button.

The cluster version API endpoint is a simple HTTP GET call that demands no additional parameters or payload. A click on the Execute button returns the actual cluster release version (see example below).

The API explorer also transforms your requests into complete cURL commands that can be used directly within your bash or command line shell to run your API requests.

Beyond creating and executing API calls directly within the Dynatrace API explorer, the OAS specification of our Dynatrace API also allows you to quickly generate any required language bindings.

Auto-generated cURL commands also enable flexible combinations of multiple API calls, which you can use to create bash automation scripts or integrate Dynatrace API calls into third-party tools, such as CI build chains.

General availability, beta, or early access?

As Dynatrace follows a bi-weekly release cycle, the Dynatrace API is continuously enhanced with each new release. The API is updated with version numbers so that existing API endpoints won’t break. However new endpoints and attributes can be added to existing API versions.

We use annotations within the OpenAPI specification to inform our API consumers about changes in the existing API (for example, newly introduced API endpoints that are still in beta or early access stage).

Each endpoint that’s still in beta or early access is marked within the Dynatrace API explorer. See the example below which shows what beta annotation looks like in the OAS specification and how this is presented within the API explorer:

Introduction of a consistent OAS API specification across all Dynatrace platform APIs is a major step toward enabling seamless integration of Dynatrace monitoring intelligence into your enterprise toolchains. The auto-generated API explorer further simplifies the execution of API calls against your monitoring environment and ensures that you always have current state information about the API version you have deployed—all directly from our production code.