Dynatrace API Guide Part 1: Classic APIs

[aeric-walls]

Intro

Hi Dynatrace Community, @clyde_anderson, @jourdan_watson and I (@aeric-walls) have put together a multi-part API guide on how to use the Dynatrace API within Swagger UI and in Postman. This will include general setup, pro tips, and visuals to get you started on extending the Dynatrace Platform. Enjoy 😄

Which APIs are Classic?

With the release Dynatrace Platform, there are new ways that we can access different API endpoints. Until the release of Dynatrace Platform, we had Configuration, Environment v1, and Environment v2 APIs. These are what we consider the “Classic” APIs.

How do we access Classic APIs?

Accessing these APIs has not changed: we still use an

• Tip: In any version of Dynatrace, navigate to Access Tokens and there will be a URL to go to the Swagger UI
  

*Note: This example only shows for a production environment. If you are using a Sprint environment, the URL would look like abc67890.sprint.dynatracelabs.com, for example.

How to Use the Swagger UI (Internal Access)

If you want to use the Swagger UI, it is quite straightforward. Below are some steps to help you get started:

1. Open Dynatrace via the Classic URL (xyz12345.live.dynatrace.com).
2. Generate an Access Token or Personal Access Token with the minimum scope necessary for what you are trying to do.
3. Navigate to the top-right and click the person icon and scroll down. You will see the options for Configuration, Environment v1, and Environment v2 APIs. Select the appropriate API.
   
4. Click "Authorize" and paste in your token.
   
5. Find the API endpoint you want to test, select "Try it out", fill out the appropriate parameters, and click "Execute".
6. From here, you can see the
   1. Curl command: Copy this to replicate this command in the command line.
   2. Request URL: The URL used when trying to access this API with the parameters you defined.
   3. Response code: The HTTP response code detailing the result of the call. For more details, see https://{environmentid}.live.dynatrace.com
      1. Type: default
      2. Whatever variable name you choose should be one that is generic – we will be reusing this variable name in other environments for easy switching between environments.
   4. Access Tokens/Personal Access Tokens: Enter your access tokens.
      1. Type: secret (this will hide the values by default unless you explicitly reveal them to help prevent your token being seen on your screen unintentionally)
      2. It is a good practice to use a standard naming scheme for your tokens so you can easily search for them later (e.g., version_Scope_[Read|Write|Ingest] --> v2_Entities_ReadWrite). Whatever format you choose should follow the same pattern for all tokens you create.
   5.  Notes:
      1. When adding a new variable, put the initial value into the “Initial value” field and the “Current value” field will auto-populate.
      2. When overwriting an existing variable, put the new value into the “Current value” field. This will allow the “Initial value” to persist in case it is ever needed for historical purposes.
      3. Save all changes by clicking the “Save” button in the top-right or the Ctrl+S shortcut.
         

Adding an API to Postman

1. Open Dynatrace via the Classic URL (xyz12345.live.dynatrace.com).
2. Navigate to the appropriate API (see Step 3 in How to Use the Swagger UI (Internal Access)).
3. Under the title of the page, you will find a hyperlink to a JSON file (red rectangle in the below image). Open this to download a JSON copy of the API. These APIs follow a standard called OpenAPI Specification.
   
4. We will now open this JSON file in a text editor and make a few changes:
   1. info.title: Update this to reflect the version (e.g., Dynatrace Environment API --> Dynatrace Environment API v2)
   2. servers.url: Replace the domain of the URL with the same value we entered for our tenant/environment variable in Postman (e.g., https://hwz97639.sprint.dynatracelabs.com/api/v2 --> {envURL}/api/v2)
   3. servers.variables: We will add a new variable with the same name as our tenant/environment variable in Postman.
   4. Save changes.
   5. In Postman, select the “Collections” button in the left-hand menu and click on “Import.” “Postman Collection” or “OpenAPI 3.0” options will both work.
      
   6. Under “Collections”, you should now see your new Collection for the API!

Before:

"variables" : { }

After:

"variables": {
  "envURL": {
    "default": ""
  }
}

Interacting with an API via Postman

Now, we will test querying against an API endpoint.

1. In the top-right of Postman, click the drop-down select the appropriate environment that we will be testing in.
   
2. Under the “Collections” tab in the left-hand menu, expand the appropriate API.
3. Expand the endpoint you want to test.
4. You will either see more folders to dig deeper into or HTTP methods like GET, POST, UPDATE, DELETE, etc. that denote a testable endpoint. Pick the endpoint and method you want to test. A new tab should open with the API endpoint and its parameters.
   
   1. Note that the URL is {{baseUrl}}/<UrlPath>?<Parameters>. If we hover over {{baseUrl}}, we can see that it takes the value from our JSON. Because we replaced the domain with the name of our tenant/environment variable from earlier, Postman will replace this with the relative domain based on the environment we have selected in Postman.
      
5. Select/Deselect the parameters you intend to use (refer to the appropriate API documentation to determine what parameters are required or optional).
6. Fill out the “Value” field for each parameter.
7. Under the “Authorization” tab, we will make a couple changes:
   1. Type: API Key
   2. Key: Authorization
   3. Value: Api-Token {{name_of_your_token}}
   4. Add to: Header

Tip: You can handle authorization on request-level (/entities), group-level (entities APIs), or collection-level (Dynatrace Environment v2)

1. Click "Send" in the top-right to execute the request.
2. In the “Body”, we can observe the response body, response code, headers, etc.
   
3. Troubleshooting Tips:
   
   1. Review the response code to determine why the call may not be working as expected.
   2. There is a “Console” button in the bottom-left corner that will show the actual request in a raw format.