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:

Topology API Workflow

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:

Type	Type	Timestamp	Description
header	INGESTION	Publish time	Description of a request
header	SCHEMA	Publish time	GET schema of the topology request
topology	N/A	N/A	List of entities

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:

Topology API to Share Device Information

The Network Operations Service (NOS) helps Augtera learn important information that you provide regarding your devices. For information on the NOS mapping, refer to the table called NOS Mapping.

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

For information on entities mapping, refer to the table called Entities Mapping. In addition, provide information on the administrative status of your device. Indicate if a device is enabled, disabled, or in maintenance mode. Use the API to provide updates on devices that are part of the pool of polled devices. For information on the mapping relationships, refer to the table called Relationships Mapping.

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

Code	Description
0	Success. The transaction was successfully posted to Augtera's backend service.
1	The message request is not supported
2	Augtera's backend service is down
3	The SCHEMA validation check failed

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.

Topology API to Verify Device Configuration

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:

View Real-time Network Device Information

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

Property	Required	Type	Description
id	YES	String	Global Unique ID for the entity
entity_type	YES	String	Specify "device"
mgmt_ipv4	YES	String	IPv4 Address of the management interface
device_name	YES	String	Hostname of the device
locations.groups.site	YES	String	Site where the entity is located
status	YES	String	Administrative state (admin_state) of the device. This can be one of the following: ENABLED MAINTENANCE DISABLED
status	NO	String	Operational status (oper_status) of the device. It can be one of the following: DeviceOperReachable DeviceOperDown DeviceOperUnknown
device_desc	NO	String	Device version
dns_device_name	NO	String	FQDN device name
os	NO	String	Operating system of the device
entity Required	NO/YES	String	role: If an entity is chosen, then a role must be specified
entity	NO	String	cluster: Indicate the cloud cluster that contains this device
locations.groups.type	NO	String	type: This can be one of the following: backbone core
locations	NO	String	type: This can be one of the following: backbone core
locations.groups.region	NO	String	region: For example, this region can be specified as us-east
locations.groups.pod	NO	String	pod: Indicate the datacenter pod id
locations.groups.dc	NO	String	dc: Data center name

Relationships Mapping

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

Table: Relationships Mapping

Property	Required	Type	Description
type	YES	String	Only "INTERFACE" is supported
if_name	YES	String	Name of the interface
if_index	NO	Integer	Interface index used for SNMP Metrics or Trap
ipv4_addr	NO	String	IP address of the interface
ipv6_addr	NO	String	IPv6 address of the interface
if_speed	NO	String	Interface speed
mtu	NO	Integer	Maximum Transmission Unit (MTU) of the interface
if_descr	NO	String	SNMP interface description
if_alias	NO	String	Alias name for interface
if_admin_status	NO	String	This can be one of the following: AdminUp AdminDown AdminTesting
if_oper_status	NO	String	This can be one of the following: OperUp OperDown OperTesting
remote	NO	Object	The remote interface that is linked to the specified interface
remote.device_name	YES	String	The name of the device to which this remote interface belongs
remote.mgmt_ipv4	YES	String	The management IP to which this remote interface belongs
remote.if_name	YES	String	Remote interface name
remote.link_type	YES	String	This can be one of the following: lldp isis
remote.ipv4_addr	NO	String	Indicate the IP Address of the remote device. This is necessary for isis link_type

NOS Mapping

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

Table: NOS Mapping

Property	NOS	Augtera Dimension	Description
site	tenant	locations.groups.site	For example, mtbb
device name	name	device_name	For example, slcar1011
device IP	ip	mgmt_ipv4	For example, 10.1.1.1
status	enabled	status.admin_state	ENABLED
status	inMaintenance	status.admin_state	MAINTENANCE
status	decommissioned	status.admin_state	DISABLED
reachability	reachable	status.oper_status	This can be one of the following: DeviceOperReachable DeviceOperDown