Topology API

Learn how Augtera can build your network topology using REST API

When Augtera learns of your devices and their relationships, Augtera can visualize your full Layer 2 and Layer 3 topology. It can auto-correlate network events and Augtera anomalies using the topology, track network changes, and monitor your devices.

You can either configure the Augtera platform with a list of your devices or use the Augtera Topology REST API to share your device information. The REST API allows the platform to automatically discover your devices and enables you to manage the lifecycle of your devices in Augtera. For example, if you use the API to change the state of a device to maintenance, it will inform the Augtera platform to appropriately modify notifications and correlation.

Further, Augtera can discover the relationships between devices and the network model using autodiscovery based on either SNMP, OpenConfig, or both. It can also base it on you sharing your network information using the Augtera Topology REST API.

This document describes the REST API commands to share your network information with the Augtera platform.

Workflow for Device and Topology Discovery

The entire workflow for endpoint discovery is represented in the following graphic:

To successfully understand the workflow, here are the high-level steps:

  1. Use a POST API call to request Augtera's SCHEMA file.

  2. Augtera will respond with a SCHEMA file in JSON format.

  3. Send a POST request with header type INGESTION .

  4. Send a POST request with header type Topology to allow Augtera to learn about devices and their relationships in your network.

  5. Augtera will respond with a success zero code. This indicates that Augtera has successfully registered your POST notifications.

  6. At any time, to verify the success of your configuration, use a GET command to see if Augtera is tracking your requested devices.

  7. Augtera will respond with your devices list in JSON format.

Access Token Authentication

If token-based authentication is enabled, use the API TOKEN provided by Augtera to reach the Augtera Platform hosted on the public cloud. Include the token in the header along with the X-Api-Key.

Example Request

Here is a sample request.

curl -H "Content-Type: application/json" -H "X-Api-Key: Customer-Access-Token" \ -d @topology.json http://<AUGTERA_PLATFORM_URL>/augtera/api/v1/network

Discovering Endpoints

For Augtera to begin tracking your devices, use the

http://customer1.console.augtera.com/augtera/api/v1/network API endpoint to direct information to the Augtera console. Replace customer1.console.augtera.com with your Augtera UI URL.

Using the Augtera API

The Header JSON API has two request types:

SCHEMA: When your request type is specified as SCHEMA, Augtera will respond with a JSON SCHEMA. Use the following CURL command to request the SCHEMA:

curl -X POST -H "Content-Type: application/json" -d @topology.json

http://<AUGTERA_PLATFORM_URL>/augtera/api/v1/network

INGESTION: When your request type is specified as INGESTION, the response will send a topology map containing a list of devices with their parameters. Use the following CURL command:

curl -X POST -H "Content-Type: application/json" -d @topology.json

http://<AUGTERA_PLATFORM_URL>/augtera/api/v1/network

For information on the top-level mapping, refer to the following table:

Device Management

For Augtera to be able to manage and monitor your devices, Augtera relies on initial device discovery to start its automated device polling process. The basic workflow is as follows:

Provide a list of all monitored devices and the following information for each:

  • " id ": A unique Global Unique Identifier (GUID) for a device

  • " entity_type ": Indicate "device" as the type

  • " mgmt_ipv4 ": IP address of the device to poll

  • " device_name ": Global unique device name

  • "site": Indicate the location of the device

Augtera reads the deviceAdminState value to check if polling or analytics are enabled on a particular device. There are three valid states per device:

  • ENABLE: A device is enabled for polling and analytics.

  • MAINTENANCE: A device is enabled for polling, but it is disabled for analytics.

  • DISABLED: A device is disabled for polling and analytics. This device will be deleted from the Augtera database.

Sample Request for Device Information

Topology API

To send a POST response to Augtera to report any topological changes, use the sample CURL request:

Example Request

curl -X POST -H "Content-Type: application/json" -d @topology.json

http://<augtera_platform_url>/augtera/api/v1/network

Augtera runs validation against the SCHEMA. Thetopology.json file displays validated JSON schema in the body of the text

Example Response

{
 "success": true,
 "code": 0,
 "message": "processed: 2 entities"
}

Here is an explanation the responses:

  • success- True confirms that the JSON body adheres to the SCHEMA

  • code-Code zero (0) indicates a successful transaction

  • message-Displays the number of entities that were processed

For more details on different status codes and what they mean, refer to the following table.

Table: Response Codes

Example Body for Topology Information

{
    "header": {
        "request_type": "INGESTION",
        "timestamp": "2022-03-25 12:35:40",
        "description": "create devices and interfaces"
    },
    "topology": [
        {
            "id": "prod:100.1.1.1",
            "entity_type": "device",
            "mgmt_ipv4": "100.1.1.1",
            "device_name": "switch11test",
            "device_desc": "Juniper ",
            "dns_device_name": "switch11test.dc1.augtera.com",
            "os": "nxos",
            "locations": {
                "groups": [
                    {
                        "site": "Brooklyn",
                        "type": "backbone",
                        "region": "us-east",
                        "pod": "xyz",
                        "dc": "1"
                    }
                ]
            },
            "status": {
                "oper_status": "DeviceOperReachable",
                "admin_state": "ENABLED"
            },
            "entity": {
                "role": "leaf",
                "cluster_name": "ija"
            },
            "relationships": {
                "edges": [
                    {
                        "local": {
                            "type": "INTERFACE",
                            "if_name": "port-channel300",
                            "if_index": 1023,
                            "ipv4_addr": "1.2.3.4",
                            "ipv6_addr": "fe:80",
                            "if_speed": "100",
                            "mtu": 1500,
                            "bw": 100,
                            "if_descr": "test intf",
                            "if_alias": "test Alias",
                            "if_admin_status": "AdminUp",
                            "if_oper_status": "OperUp"
                        },
                        "remote": {
                            "device_name": "switch12test",
                            "mgmt_ipv4": "100.1.1.2",
                            "if_name": "port-channel200",
                            "ipv4_addr": "2.2.3.4",
                            "link_type": ["lldp", "isis"]
                        }
                    }
                ]
            }
        },
        {
            "id": "prod:100.1.1.2",
            "entity_type": "device",
            "device_id": "abcde3",
            "device_id_type": "spine",
            "device_desc": "Juniper ",
            "device_name": "switch12test",
            "dns_device_name": "switch12test.dc1.augtera.com",
            "mgmt_ipv4": "100.1.1.2",
            "os": "nxos",
            "locations": {
                "groups": [
                    {
                        "site": "Jersey",
                        "type": "backbone",
                        "region": "us-east",
                        "pod": "xyz",
                        "dc": "1"
                    }
                ]
            },
            "status": {
                "oper_status": "DeviceOperReachable",
                "admin_state": "ENABLED"
            },
            "entity": {
                "role": "leaf",
                "cluster_name": "ija"
            },
            "relationships": {
                "edges": [
                    {
                        "local": {
                            "type": "INTERFACE",
                            "if_name": "port-channel200",
                            "if_index": 1024,
                            "ipv4_addr": "2.2.3.4",
                            "ipv6_addr": "fe:80",
                            "if_speed": "100",
                            "mtu": 1500,
                            "bw": 100,
                            "if_descr": "test intf",
                            "if_alias": "test Alias",
                            "if_admin_status": "AdminUp",
                            "if_oper_status": "OperUp"
                        },
                        "remote": {
                            "device_name": "switch11test",
                            "mgmt_ipv4": "100.1.1.1",
                            "if_name": "port-channel300",
                            "ipv4_addr": "1.2.3.4",
                            "link_type": ["lldp", "isis"]
                        }
                    }
                ]
            }
        }
    ]
}

Verify your Configuration

After you have sent your POST requests to Augtera and want to verify what devices are being tracked by Augtera, use this GET request.

HTTP GET customer-platform-url/augtera/api/get_model_devices

Again, replace customer-platform-url with your Augtera platform URL.

This request helps retrieve a list of network devices that have been created by Augtera services. Use this API to verify the state created by v1/network APIs.

Augtera will respond with a list of devices that Augtera will monitor. The following graphic represents this workflow.

At any time, use the Augtera UI to view any real-time updates based on any REST API event. This data is visible from the Trends page. To view updated information, choose

eventSource ="internal_event", eventType = "v1/network" .

The UI will display information of this nature:

Mappings Reference

This section contains the field descriptions for the Entities, Relationships, and the NOS mappings.

Entities Mapping

The following table lists the entities mappings and provides a brief description for each field.

Table: Entities Mapping

Relationships Mapping

The following table lists the relationships mapping and provides a brief description for each field.

Table: Relationships Mapping

NOS Mapping

The following table lists the NOS mappings and provides a brief description for each field.

Table: NOS Mapping

Last updated