Migrate from Topology and Smartscape API to Monitored entities API

The Topology and Smartscape API has been deprecated with Dynatrace version 1.263. Its replacement is the Monitored entities API. We recommend that you migrate to the new API at your earliest convenience.

This migration affects endpoint URLs, query parameters, and response/request body parameters, as well as the scope of the token for request authentication.

New features

The Monitored entities API offers you the following new features:

  • Entity type agnostic endpoint—you can query every type of entity via the same URL
  • Powerful entity selector that helps you to filter entities you want to read
  • Unified timeframe selector
  • Customizable return value—you can control which entity properties are included in the response
  • Entity types endpoints
  • Custom tags endpoints

Base URL

new Monitored entities
old Topology and Smartscape
/api/v2/entities
/api/v1/entity/applications
/api/v1/entity/infrastrucutre/hosts
/api/v1/entity/infrastrucutre/processes
/api/v1/entity/infrastrucutre/process-groups
/api/v1/entity/services
/api/v2/entities/custom
/api/v1/entity/infrastructure/custom/{customDeviceId}
/api/v2/tags
/api/v1/entity/applications/{meIdentifier}
/api/v1/entity/infrastrucutre/hosts/{meIdentifier}
/api/v1/entity/infrastrucutre/process-groups/{meIdentifier}
/api/v1/entity/services/{meIdentifier}

Authentication token scope

new Monitored entities
old Topology and Smartscape
Read entities (entities.read)
Write entities (entities.write)
Access problem and event feed, metrics, and topology (DataExport)

Parameters

To learn about new query/body parameters, see the documentation of individual requests in Monitored entities API.

Changes in workflow

With the upgrade to the Monitored entities API, some workflows require sending additional requests or calling additional endpoints. Be sure to adapt your automation accordingly.

Pagination

When you query entities in a bulk, pagination is used to reduce the payload size.

  1. Specify the number of entities per page in the pageSize query parameter.
  2. Use the cursor from the nextPageKey field of the previous response in the nextPageKey query parameter to obtain subsequent pages.

Create custom devices

In the Monitored entities API, you can't assign tags to the custom device upon creation. If you need to assign tags to your custom device, use a separate request to the POST custom tags endpoint.

Report data to custom devices

In the Monitored entities API, you can't report data to custom devices. Use the POST ingest data points call instead.

Examples

Here are some examples of differences in API usage.

List entities

In this example, we're querying the list of hosts that were active within the last 2 hours. Also, we don't need the full information about the host: we only need monitoring mode and the list of tags, assigned to the host. The result is truncated to two entries.

Compare the following tabs to see how we do this using the new Monitored entities API and the deprecated Topology and Smartscape API:

In the Monitored entities API:

  • You can control which fields are returned (via the fields parameter). In this example, we use the monitoringMode and tags fields. Type, display name, and entity ID are always included in the response.
  • The timeframe is defined via the from query parameter. It supports multiple formats; see the individual request documentation to learn more about them.
  • The result of the query is split into pages. You can control the page size with the pageSize parameter. In this example, the parameter is not set; therefore, the default of 50 entries per page is used.

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/entities?fields=properties.monitoringMode,tags&entitySelector=type(%22HOST%22)&from=now-2h

Query parameters

fields=properties.monitoringMode,tags
entitySelector=type("HOST")
from=now-2h

Response body

{
  "totalCount": 85,
  "pageSize": 50,
  "nextPageKey": "AQAMdHlwZSgiSE9TV==",
  "entities": [
    {
      "entityId": "HOST-01A00204B50FF735",
      "type": "HOST",
      "displayName": "easytravel-backend.internal",
      "properties": {
        "monitoringMode": "FULL_STACK"
      },
      "tags": [
        {
          "context": "CONTEXTLESS",
          "key": "Stage",
          "value": "PreProduction",
          "stringRepresentation": "Stage:PreProduction"
        },
        {
          "context": "CONTEXTLESS",
          "key": "OS",
          "value": "Linux",
          "stringRepresentation": "OS:Linux"
        },
        {
          "context": "CONTEXTLESS",
          "key": "backend",
          "stringRepresentation": "backend"
        }


      ]
    },
    {
      "entityId": "HOST-0AF138A0258C7DFF",
      "type": "HOST",
      "displayName": "easytravel-frontend.prod",
      "properties": {
        "monitoringMode": "FULL_STACK"
      },
      "tags": [
        {
          "context": "CONTEXTLESS",
          "key": "Stage",
          "value": "Production",
          "stringRepresentation": "Stage:Production"
        },
        {
          "context": "CONTEXTLESS",
          "key": "OS",
          "value": "Windows",
          "stringRepresentation": "OS:Windows"
        },
        {
          "context": "CONTEXTLESS",
          "key": "frontend",
          "stringRepresentation": "frontend"
        }
      ]
    }
  ]
}

Assign entity tags

In this example, we assign additional tags (Datacenter:Linz and Rack:014) to hosts from the list entities example.

Compare the following tabs to see how we do this using the new Monitored entities API and the deprecated Topology and Smartscape API:

In the new Monitored entities API, you can assign tags to multiple entities at the same time by selecting them via the entity selector. In this example, we select hosts by their entity IDs.

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/tags?entitySelector=entityId(%22HOST-01A00204B50FF735%22,%22HOST-0AF138A0258C7DFF%22)

Query parameters

entitySelector=entityId("HOST-01A00204B50FF735","HOST-0AF138A0258C7DFF")

Request body

{
  "tags": [
    {
      "key": "Datacenter",
      "value": "Linz"
    },
    {
      "key": "Rack",
      "value": "014"
    }
  ]
}

Response body

{
  "matchedEntitiesCount": 2,
  "appliedTags": [
    {
      "context": "CONTEXTLESS",
      "key": "Datacenter",
      "value": "Linz",
      "stringRepresentation": "Datacenter:Linz"
    },
    {
      "context": "CONTEXTLESS",
      "key": "Rack",
      "value": "014",
      "stringRepresentation": "Rack:014"
    }
  ]
}

Create custom devices

In this example, we create a custom device with the ID of restExample and the following parameters:

  • type: F5-Firewall
  • IP address 172.16.115.211
  • listen port 9999

Compare the following tabs to see how we do this using the new Monitored entities API and the deprecated Topology and Smartscape API:

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/entities/custom

Request body

{
  "customDeviceId": "restExample",
  "displayName": "F5 Firewall 24",
  "ipAddresses": ["172.16.115.211"],
  "listenPorts": ["9999"],
  "type": "F5-Firewall",
  "favicon": "http://assets.dynatrace.com/global/icons/f5.png",
  "configUrl": "http://192.128.0.1:8080",
  "properties": {
    "Sample Property 1": "Sample value 1"
  }
}

Response body

{
  "entityId": "CUSTOM_DEVICE-1525F193C0578E2C",
  "groupId": "CUSTOM_DEVICE_GROUP-FC2E2ABF54F513D8"
}

Related topics