Viewing static topologies with API

You can use the API to render a static topology view through a cURL command, which you then download as an image. You use the resourceId parameter to seed the topology, and then define a number of other parameters to generate a static server-side topology image.

Deprecation notice: The ability to use the UI-API to render a static topology view through cURL command is no longer being used and can be removed in a future release.

Before you begin

To define a cURL string that renders a topology through the API, you must know the URL for your core host. You must also know the resource ID for your seed resource, as well as the required authentication credentials.

About this task

The API is available on the following endpoints:

  • https://<host>/1.0/ui-api/render/svg
  • https://<host>/1.0/ui-api/render/png

After you construct your cURL command in the following steps, you can use the command to download a static topology view as either a PNG or SVG image.

In addition to the resourceId parameter, you can use a Basic authentication header when calling the API. With this header, you can call the API without needing to log in to the IBM Cloud Pak for AIOps console first.

Tips:

  • You can use the width and height URL parameters (exclusively for use with the UI-API) to set the size of the image produced. The default size is 1000 x 700.
  • You can include advanced resource or relationship filters in your URL by specifying 'type'. For more information about topology filtering, see Viewing a topology.
  • You can change the label length for your resource types. For more information, see Editing resource type styles.

Example URLs

  • PNG example

    curl -X GET "https://example.host.com/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="

  • SVG example

    curl -X GET "https://example.host.com/1.0/ui-api/render/svg?resourceId=sl1RQ5NCR_ykgciQCTkFGA" -H "accept: image/svg+xml" -H "authorization: Basic YXNtOmFzbQ=="

Where:

  • The IBM Cloud Pak® for AIOps core host is asm.example.host.com
  • The resourceId that identifies the seed resource is sl1RQ5NCR_ykgciQCTkFGA
  • The output format is specified by either png or svg
  • The authorization method is specified as Basic
  • The encrypted user credentials (username and password) are YXNtOmFzbQ==

Procedure

  1. Obtain your resource ID, authentication credentials, and host URL.

  2. Define a cURL call by editing the parameters, as shown in the following examples.

Example commands

Specify a seed resource by ID

The following cURL call example renders a simple IBM Cloud Pak for AIOps topology view with a host URL of example.host.com and a port number of 3080. The view is based on the resourceId parameter with the value of sl1RQ5NCR\_ykgciQCTkFGA. It returns a png image, and performs Basic access authentication using the encrypted username and password credentials (YXNtOmFzbQ==).

curl -X GET "https://example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="

Specify the hop numbers and types

The image that is returned by this cURL call has the same seed resource as before, but now with the amount of hops set at 3, and a hopType of host. The hopType parameter is only required if you want to use the host-to-host hop type (element-to-element is the default).

curl -X GET "https://example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&hopType=host" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="

Specify focus areas for large topologies

The image that is returned by this cURL call has the same seed resource as before (now with a hop count of three), but now zooms in on the area that is specified by the focusId parameter, preventing large topologies from being displayed with potentially too much information on view.

curl -X GET "https://example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&focusId=<resource_id>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="

Specify more resources to be highlighted

The image returned that is by this cURL call has the same seed resource as before with a hop count of three, but now uses the selectedIds parameter to specify other non-seed resources through their IDs to highlight when the image is rendered.

curl -X GET "https://example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&selectedIds=<resource_id> <resource_id>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="

Specify 'get neighbor' expansion

The image that is returned by this cURL now includes a neighbourRequests parameter that gathers a number of other neighboring resources for display, each identified by its resource ID. The neighbourRequests parameter expects an array of space-separated ID strings.

curl -X GET "https://example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&neighbourRequests=<resource_id> <resource_id>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="

Specify advanced resource filters

The image returned now includes a resourceFilter parameter that filters out all resources of a specified type. The resourceFilter parameter expects an array of space-separated, previously defined resource types.

curl -X GET "https://example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&resourceFilter=<Type1> <Type2>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="

Specify advanced relationship filters

The image that is returned includes the relation filter parameter (relationFilter) to filter out all relationships of a specified type. The relationFilter parameter expects an array of space-separated, previously defined resource types.

curl -X GET "https://example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&relationFilter=<Type1> <Type2>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="

Specify time point

The image that is returned reflects the state of the topology at a specific point in history (in Unix time). The time parameter expects the time entered in Unix time.

curl -X GET "https://example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&time=<unixTimeMilliseconds>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="

Specify delta history mode

The image returned shows the topology in delta history mode, with the specified time as a reference point and the deltaTime parameter as the point to delta against.

curl -X GET "https://example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&time=<unixTimeMilliseconds>&**deltaTime**=<unixTimeMilliseconds>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="

What to do next

With the topology images created, you can download and save the images for quick access to specific views, or share the images with other users to provide them with specific, instant information.