netbrain integrated edition api and system integration guide · netbrain restful apis the system...

Version 7.1a | Last Updated 2018-11-22 Copyright ©2004-2018 NetBrain Technologies, Inc. All rights reserved.

NetBrain® Integrated Edition 7.1 API User Guide

Contents

1. RESTful API ................................................................................................................................................................................... 7

1.1. Authentication and Initialization .................................................................................................................................... 10

1.1.1. Log in to get an authentication token ................................................................................................................. 11

1.1.2. Get all accessible tenants ....................................................................................................................................... 12

1.1.3. Get all accessible domains of a tenant................................................................................................................ 13

1.1.4. Specify a domain to work on ................................................................................................................................. 14

1.1.5. Log out from a session ........................................................................................................................................... 14

1.2. Discovery ............................................................................................................................................................................ 15

1.2.1. Get all discovery tasks in a domain ...................................................................................................................... 16

1.2.2. Add IPs as seeds to a discovery task ................................................................................................................... 17

1.2.3. Remove IPs from a discovery task ....................................................................................................................... 18

1.2.4. Get all IPs added to a discovery task ................................................................................................................... 19

1.2.5. Run a discovery task now ....................................................................................................................................... 20

1.2.6. Get the status of a discovery task ........................................................................................................................ 21

1.2.7. Get the results of discovered devices.................................................................................................................. 22

1.2.8. Get the live access logs of devices ....................................................................................................................... 23

1.3. Device Information ........................................................................................................................................................... 24

1.3.1. Get all devices in a domain .................................................................................................................................... 24

1.3.2. Get the value of a device attribute ....................................................................................................................... 25

1.3.3. Get all interfaces of a device ................................................................................................................................. 26

1.3.4. Get the value of an interface attribute ................................................................................................................ 27

1.3.5. Get all modules of a device.................................................................................................................................... 29

1.3.6. Get the value of a module attribute .................................................................................................................... 29

1.3.7. Get the neighbors of a device by topology type ............................................................................................... 30

1.3.8. Get the connected switch ports of an end system ........................................................................................... 31

1.3.9. Get device configuration ........................................................................................................................................ 32

1.4. Device Management......................................................................................................................................................... 33

1.4.1. Get devices in a device group ............................................................................................................................... 33

1.4.2. Get the Front Server of a device ........................................................................................................................... 34

1.4.3. Remove devices from a domain in batch ........................................................................................................... 35

1.4.4. Get device group list................................................................................................................................................ 35

1.5. Attribute Management .................................................................................................................................................... 36

1.5.1. Create a customized device attribute .................................................................................................................. 37

1.5.2. Set value for a specified device attribute ........................................................................................................... 38

1.5.3. Delete a device attribute ........................................................................................................................................ 39

1.5.4. Create a customized interface attribute ............................................................................................................. 39

1.5.5. Set value for a specified interface attribute ....................................................................................................... 40

1.5.6. Delete an interface attribute ................................................................................................................................. 41

1.5.7. Create a customized module attribute ............................................................................................................... 42

1.5.8. Set value for a specified module attribute ......................................................................................................... 43

1.5.9. Delete a module attribute ...................................................................................................................................... 44

1.6. Site Information................................................................................................................................................................. 45

1.6.1. Get the basic information of a site ....................................................................................................................... 45

1.6.2. Get child sites of a specific site ............................................................................................................................. 46

1.6.3. Get devices in a specific site .................................................................................................................................. 47

1.7. Site Modification ............................................................................................................................................................... 48

1.7.1. Create a transaction to start site modification .................................................................................................. 49

1.7.2. Remove a site transaction...................................................................................................................................... 49

1.7.3. Keep transaction alive............................................................................................................................................. 50

1.7.4. Create a parent site ................................................................................................................................................. 51

1.7.5. Create a leaf site ...................................................................................................................................................... 51

1.7.6. Create sites ................................................................................................................................................................ 52

1.7.7. Delete a site .............................................................................................................................................................. 53

1.7.8. Add devices to a site ................................................................................................................................................ 54

1.7.9. Replace devices in a site ......................................................................................................................................... 55

1.7.10. Remove devices from a site ................................................................................................................................... 55

1.7.11. Commit modifications to rebuild a site ............................................................................................................... 56

1.8. Path ...................................................................................................................................................................................... 57

1.8.1. Calculate a Path ........................................................................................................................................................ 57

1.8.2. Get Path Calculation Result ................................................................................................................................... 59

1.8.3. Get the gateway information of a device............................................................................................................ 60

1.8.4. Stop a path ................................................................................................................................................................ 60

1.8.5. Get path calculation status .................................................................................................................................... 61

1.9. System Management ....................................................................................................................................................... 62

1.9.1. Add a tenant ............................................................................................................................................................. 62

1.9.2. Update a tenant ....................................................................................................................................................... 63

1.9.3. Delete a tenant ......................................................................................................................................................... 64

1.9.4. Assign users to a tenant ......................................................................................................................................... 65

1.9.5. Add a domain ........................................................................................................................................................... 66

1.9.6. Update a domain ..................................................................................................................................................... 67

1.9.7. Delete a domain ....................................................................................................................................................... 68

1.9.8. Assign users to a domain ....................................................................................................................................... 69

1.9.9. Remove users from a domain ............................................................................................................................... 70

1.9.10. Add a role .................................................................................................................................................................. 71

1.9.11. Update a role ............................................................................................................................................................ 71

1.9.12. Delete a role .............................................................................................................................................................. 72

1.9.13. Get role information ............................................................................................................................................... 73

1.10. Topology Building ......................................................................................................................................................... 74

1.10.1. Build L2 topology ..................................................................................................................................................... 74

1.10.2. Build L3 topology ..................................................................................................................................................... 75

1.10.3. Get the status of topology building ..................................................................................................................... 75

1.10.4. Get One-IP Table ...................................................................................................................................................... 76

1.11. Network Settings ........................................................................................................................................................... 78

1.11.1. Add network credentials ........................................................................................................................................ 78

1.11.2. Edit network credentials......................................................................................................................................... 82

1.11.3. Delete network credentials .................................................................................................................................... 86

1.12. Map .................................................................................................................................................................................. 87

1.12.1. Export a map............................................................................................................................................................. 88

1.12.2. Delete a map ............................................................................................................................................................. 88

1.12.3. Get the file list ........................................................................................................................................................... 89

1.12.4. Get device groups .................................................................................................................................................... 91

1.13. Benchmark ..................................................................................................................................................................... 92

1.13.1. Add a benchmark task ............................................................................................................................................ 92

1.13.2. Update a benchmark task ...................................................................................................................................... 94

1.13.3. Delete a benchmark task ....................................................................................................................................... 96

1.13.4. Run a benchmark task immediately .................................................................................................................... 97

1.13.5. Get the status of a benchmark task ..................................................................................................................... 97

1.13.6. Get the run records of a benchmark task .......................................................................................................... 98

1.14. Tuning Devices ............................................................................................................................................................... 99

1.14.1. Tune devices ........................................................................................................................................................... 100

1.14.2. Get the results of tuning devices ........................................................................................................................ 100

1.15. Users .............................................................................................................................................................................. 102

1.15.1. Add users ................................................................................................................................................................. 102

1.15.2. Update users ........................................................................................................................................................... 104

1.15.3. Delete users ............................................................................................................................................................ 105

1.15.4. Get the usage report of users ............................................................................................................................. 106

1.15.5. Get user information............................................................................................................................................. 107

1.16. API Status Code List .................................................................................................................................................... 108

1.17. Device Type Name and ID ......................................................................................................................................... 111

1.18. Best Practices and Use Cases for NetBrain Rest APIs ......................................................................................... 116

1.18.1. Best Practice to Use NetBrain as CMDB via APIs ............................................................................................ 117

1.18.2. Use Case - Manage Your NetBrain Data via APIs ............................................................................................ 122

1.18.3. Use Case - Return Hop List of a Path in Third-party System ........................................................................ 138

NetBrain Integrated Edition 7.1a API User Guide | 7

1. RESTful API

For enterprises deploying centralized database such as IP Address Management (IPAM) or Configuration Management Database (CMDB) to maintain basic device information, NetBrain can synchronize with these CMDB or inventory systems as well as serve as a CMDB for them to query data stored in NetBrain as a single source of truth.

NetBrain RESTful APIs

The system provides dozens of RESTful APIs to read (Get) and write (Set) data.

Tip: You can also view these APIs including its parameters, responses, sample codes and more details in a Swagger page, and try out each API in the page.

Category Description API Lists

Authentication and Initialization

Initialize and Authenticate user information before querying system data.

Log in to get an authentication token

Log out from session

Get all accessible tenants

Get all accessible domains of a tenant

Specify a domain to work on

Discovery Manage and view discovery tasks. Get a list of discovery tasks in a domain

Add IPs as seeds to a discovery task

Remove IPs from a discovery task

https://ite.netbraintech.com/swagger/

8 | NetBrain Integrated Edition 7.1a API User Guide


Get all IPs added to a discovery task

Run a discovery task now

Get the running status of a discovery task

Get the discovery results of devices

Get the live access logs of devices

Site Information Get the information of a site. Get the basic information of a site

Get child sites of a specific site

Get devices in a specific site

Site Modification Make modifications to a site. Create a transaction to start site modification

Remove a site transaction

Commit modifications to rebuild a site

Send heartbeat call to keep site transaction alive

Create a parent site

Create a leaf site

Create sites

Delete a site

Add devices to a site

Replace devices in a site

Remove devices from a site

Device Management View devices and device data, add devices to a domain or remove devices from a domain.

Get devices by IP addresses

Get devices in a device group

Get the front server of a device

Remove devices from a domain in batch

Get device group list

Device Information Get information about devices. Get all devices in a domain

Get the value of a specified device attribute

Get all interfaces of a device

Get the value of a specified interface attribute

Get all modules of a device

Get the value of a specified module attribute

Get the neighbors of a device by topology type

Get the connected switch ports of an end system

Get device configuration



Device and Interface Attribute Management

Manage device and interface attributes, such as put delete or create an attribute.

Create a customized device attribute

Set value for a specified device attribute

Delete a device attribute

Create a customized interface attribute

Set value for a specified interface attribute

Delete an interface attribute

Create a customized module attribute

Set value for a specified module attribute

Delete a module attribute

Path Calculate paths and view path results. Calculate a path

Get path calculation result

Get the gateway information of a device

Stop a path

Get path calculation status

System Management Manage your NetBrain system. Add a tenant

Update a tenant

Delete a tenant

Assign users to a tenant

Add a domain

Update a domain

Delete a domain

Assign users to a domain

Remove users from a domain

Add a role

Update a role

Delete a role

Get role information

Topology Building Build Layer 2 and Layer 3 topology in a domain.

Build L2 topology

Build L3 topology

Get the running status of a topology building task

Get One-IP Table

Network Settings Manage credentials in a network setting.

Add network credentials

Edit network credentials



Delete network credentials

Map Export a map or delete a map. Export a map

Delete a map

Get the file list (Embedded Map)

Get device group (Embedded Map)

Benchmark Manage benchmark tasks in a domain. Add a benchmark task

Update a benchmark task

Delete a benchmark task

Run a benchmark task immediately

Get the status of a benchmark task

Get the execution history of a benchmark task

Users Manage user accounts. Add users

Update users

Delete users

Get the usage report of users

Get user information

Tuning devices Tune network devices and get the tuning result.

Tune devices

Get the results of tuning devices

1.1. Authentication and Initialization

To use NetBrain APIs, you need to authenticate user information to get access token. With the access token, you

can specify a tenant/domain to get started with API calls.

In the Authentication category, the following APIs are included:

Log in to get an authentication token

Get all accessible tenants

Get all accessible domains of a tenant

Specify a domain to work on

Log out from a session


1.1.1.Log in to get an authentication token

Use this API call to get an authentication token and start a session.

Resource Information

Method URL Required authentication

POST base_url/V1/Session No

Tip: The base URL is http(s)://<IP address of your NetBrain Web API Server>/ServicesAPI/API.

Parameters

Name Description Example

body *required (body)

The body contains two parameters:

username*(string): the username to log into your NetBrain domain.

password*(string): the password to log into your NetBrain

domain.

authentication_id (string): the authentication ID of an external user through SSO, LDAP/AD or TACACS. This parameter is only required for an external user and the value is alias.

{ "username": "NetBrain", "password": "NetBrain" }

Note: The content type that NetBrain APIs support is application/json.

Response

Parameter Type Description Example

token string The returned authentication token. { "token": "301ebdd8-0045-429d-8807-c51b8db7f5f0", "statusCode": "790200", "statusDescription": "Success" }

statusCode integer The returned status code of executing the API.

statusDescription string The explanation of the status code.

After receiving a token, associate your session with a tenant ID and domain ID. To find your tenant and domain ID, call APIs to get a list of tenants and domains that can be used.


1.1.2.Get all accessible tenants

Use this API to view accessible tenants (return tenant ID and names). The accessible tenants depend on privileges

that the logged-in user has. Users with system admin permissions would be able to see all tenants.



GET /V1/CMDB/Tenants Yes

Parameters

Name Description

Token*required (header)

Input the token received from the API Log in to get an authentication token.

Example:

{ "token": "301ebdd8-0045-429d-8807-c51b8db7f5f0" }

Response


tenants list A list of all accessible tenants. { "tenants": [ { "tenantId": "3e75247a-309c-4231-96a5-823b6cb1e78d", "tenantName": "bos_office" }, { "tenantId": "5a75247a-309c-4231-96a5-823b6cb1e78d", "tenantName": "ny_office" } ] }

tenantId string The tenant ID.

tenantName string The tenant name.




1.1.3.Get all accessible domains of a tenant

Use this API to get accessible domains in a specific tenant. The accessible domains depend on permissions that the login user has. Users with system admin or tenant admin permissions would be able to see all domains in a

tenant.



GET /V1/CMDB/Domains Yes

Parameters

Name Description



tenantId (query)

Input the ID of the tenant that you want to get its domains. Get a tenant ID via the API get all accessible tenants.

Response


domains list A list of all accessible domains. { "domains": [ { "domainId": "4e75247a-309c-4231-96a5-823b6cb1e78d", "domainName": "domain1" }, { "domainId": "5e75247a-309c-4231-96a5-823b6cb1e78d", "domainName": "domain2" } ] }

domainId string The domain ID.

domainName string The domain name.




1.1.4.Specify a domain to work on

Use this API to specify a domain to work on to get or set NetBrain data by associating domainID to the current

session.



PUT /V1/Session/CurrentDomain Yes

Parameters

Name Description



Request*required (body)


tenantId*(string): input the ID of the target tenant. Get a tenant ID by using the API Get all accessible tenant.

domainId*(string): input the ID of the target domain. Get a domain ID by using the API Get all

accessible domains of a tenant.

Example:

{ "tenantId": "3e75247a-309c-4231-96a5-823b6cb1e78d", "domainId": "4e75247a-309c-4231-96a5-823b6cb1e78d" }

Response



{ "statusCode": 790200, "statusDescription": "success" } statusDescription string The explanation of the status code.

1.1.5.Log out from a session

Use this API to log out from the current session.




DELETE /V1/Session Yes

Parameters

Name Description Example

body *required (body)

The body contains one parameter:

token*(string): input the token received from login.

{ "token": "301ebdd8-0045-429d-8807-c51b8db7f5f0" }

Response




1.2. Discovery

Uses the following APIs to manage your network discovery tasks in a domain:

Get a list of discovery tasks in a domain

Add IPs as seeds to a discovery task

Remove IPs from a discovery task

Get all IPs added to a discovery task

Run a discovery task now

Get the running status of a discovery task

Get the discovery results of devices

Get the live access logs of devices


1.2.1.Get all discovery tasks in a domain

Use this API to get all discovery tasks in the current domain.

Tip: If there are no discovery tasks in the system, add a new discovery task from the Domain Management page. In the discovery task, select Once on the Frequency tab and Discover the following IPs on the Discovery Seed tab.



GET /V1/CMDB/Discovery/Tasks Yes

Parameters

Name Description


Place the token received from the API Log in to get an authentication token.

Response


tasks list A list of all discovery tasks. { "statusCode": 790200, "statusDescription": "success", "tasks": [ { "id": "1696faa7-749c-78a7-eaad-fcf815b11e4a", "name": "Scheduled System Discovery", "enable": true, "lastStatus": "", "lastRunSpan": "00:00:00", "curStatus": "Not Started", "nextRunTime": "1/2/3000,12:00:00 AM", "frequency": "Once" }, { "id": "1696faa7-749c-78a7-eaad-fcf815b11e4b", "name": "Scheduled Discovery1", "enable": true, "lastStatus": "",

id string The ID of a discovery task.

name string The name of a discovery task.

enable bool Whether a discovery task is enabled.

lastStatus string The last run (result) status of a discovery task.

lastRunSpan integer The duration of the last run of a discovery task.

curStatus string The current status of a discovery task.

nextRunTime string The start time of the next run of a discovery task.

frequency string The run frequency of a discovery task.




statusDescription string The explanation of the status code. "lastRunSpan": "00:00:00", "curStatus": "Not Started", "nextRunTime": "2/2/3000,12:00:00 AM", "frequency": "Once" } ] }

1.2.2.Add IPs as seeds to a discovery task

Use this API to add a list of IP addresses as seeds to an existing scheduled discovery task.



POST /V1/CMDB/Discovery/Tasks/{task}/Seeds Yes

Parameters

Name Description



task*required (path)

Input the name or ID of the scheduled discovery task. Get a task ID by using the API Get all discovery tasks in a domain.


The body contains the following parameters:

seeds* (list): a list of IP entries. The following is the information of each seed.

o mgmtIP* (string): the management IP address of a device.

o cliType (integer): the access method to the device. When it is null, the SNMP method will be used.

0: Telnet

1: SSH

o userName (string): the username to access the device.

o password (string): the password to access the device.

o privilegeUsername (string): the username to enter the privileged mode of the device.

o privilegePassword (string): the password to enter the privileged mode of the device.

o designatedCredentials (bool): determine whether the API only uses the credentials you have specified. If false, the API will use credentials in network settings.


Name Description

o snmpCommunityString (string): the SNMP community string to access the device.

o frontServerOrGroupAlias (string): the alias of NetBrain Front Server to access your live network.

Example:

{ "seeds": [ { "mgmtIP": "string", "cliType": 0, "userName": "NetBrain", "password": "NetBrain", "privilegeUsername": "string", "privilegePassword": "string", "designatedCredentials": true, "snmpCommunityString ": "string", "frontServerOrGroupAlias": "string" } ] }

Response




1.2.3.Remove IPs from a discovery task

Use this API to remove specific seed IPs from a discovery task.



DELETE /V1/CMDB/Discovery/Tasks/{task}/Seeds Yes

Parameters

Name Description




Name Description


Input the name or ID of the scheduled discovery task. Get a task ID by using the API Get all discovery tasks in a domain.



IPs (list): A list with IPs that you want to remove.

Example:

{ "IPs": [ "172.24.101.12" ] }

Response




1.2.4.Get all IPs added to a discovery task

Use this API to get all IPs added to a discovery task.



GET /V1/CMDB/Discovery/Tasks/{task}/Seeds Yes

Parameters

Name Description




Input the name or ID of the scheduled discovery task added on benchmark page. Get a task ID by using the API Get all discovery tasks in a domain.

Response



IPs list A list with all seed IPs. { "IPs": [ "192.168.0.1" ], "statusCode": 790200, "statusDescription": "success" }



1.2.5.Run a discovery task now

Use this API to run a scheduled discovery task right away.



POST /V1/CMDB/Discovery/Tasks/{task}/Run Yes

Parameters

Name Description





Response





1.2.6.Get the status of a discovery task

Use this API to get the status of a scheduled discovery task.

Note: If too many devices are scheduled to run in one task (for example, up to 50,000 network devices), this API may return a large amount of data and cause a performance issue.



GET /V1/CMDB/Discovery/Tasks/{task}/Status Yes

Parameters

Name Description





Response



{ "statusCode": 790200, "statusDescription": "success", "taskStatus": 10 }


taskStatus integer The status of the task. The status has the following values:

-1: Unknown

0: Never run

2: Running

10: Succeeded

11: Succeeded with warnings

20: Failed

30: Manually stopped

31: Automatically stopped due to timeout set by users or another system setting.


1.2.7.Get the results of discovered devices

Use this API to get the results of discovered devices for a discovery task, such as whether succeeded to get the

config of a device.



GET /V1/CMDB/Discovery/Tasks/{task}/Results Yes

Parameters

Name Description





IPs (query)

The list of IPs of discovered devices. Returns results of all devices if not specified.

Response


Devices list A list of discovered devices. { "statusCode": 790200, "statusDescription": "success", "devices": [ { "domainId": "5e75247a-309c-4231-96a5-823b6cb1e78d", "source": "Scan 172.24.101.12/32", "hostname": "Bos-Core1", "frontServer": "10.10.1.43", "ping": "Succeeded", "SNMP": "nb", "vendor": "Cisco", "oid": "1.3.6.1.4.1.9.1.324", "type": "Cisco IOS Switch", "config": "Succeeded", "telnetSSH": "Succeeded" }

domainId string The ID of the domain that a device belongs to.

source string The IP from which a device was discovered.

hostname string The hostname of a device.

frontServer string The Proxy Server used to discover a device.

ping string The ping to a device succeeded or failed.

SNMP string The SNMP community string of a device.

vendor string The vendor of a device.

oid string The OID of a device.



type string The type of a device. ] }

config string Obtaining device configuration succeeded or failed.

telenetSSH string Accessing a device via SSH or Telnet succeeded or failed.



1.2.8.Get the live access logs of devices

Use this API to get the live logs of discovered devices.



GET /V1/CMDB/Discovery/Tasks/{task}/LiveAccessLog Yes

Parameters

Name Description




Input the name or ID of a scheduled discovery task. Get a task ID by using the API Get all discovery tasks in a domain.

IPs (query)

The list of IPs of discovered devices. Returns live logs of all devices if not specified.

Response


statusCode integer The returned status code of executing the API. { "statusCode": 790200, "statusDescription": "success", "devices": [


devices list A list of discovered devices.



mgmtIP string The management IP of a device. { "mgmtIP": "172.24.101.12", "liveLogs": "xxx" } ] }

livelogs string The live logs of a device.

1.3. Device Information

Use the following APIs to query the information stored in a device.

Get all devices in a domain

Get the value of a specified device attribute

Get all interfaces of a device

Get the value of a specified interface attribute

Get all modules of a device

Get the value of a specified module attribute

Get the neighbors of a device by topology type

Get the connected switch ports of an end system

1.3.1.Get all devices in a domain

Use this API to get the corresponding device by an IP address or device name. If neither hostname nor IP address

is set, return all devices in the current domain.



GET /V1/CMDB/Devices Yes

Parameters

Name Description




Name Description

hostname (query)

Enter hostname to find the corresponding device’s details.

If neither hostname or IP address is set, all devices of the current domain will be returned.

If both hostname and IP address are set, the hostname will take precedence.

ip (query)

Enter an IP address to find the corresponding device’s details.

If neither hostname or IP address is set, all devices of the current domain will be returned.

If both hostname and IP address are set, the hostname will take precedence.

Response


devices list A list with of devices in a domain. { "statusCode": 790200, "statusDescription": "success", "devices": [ { "id": "7d47c791-84cb-4bdb-9d2c-abbfafe71b2e", "mgmtIP": "10.10.7.253", "hostname": "Bos-Core", "deviceTypeName": "Cisco Router" } ] }

id string The ID of a device.

mgmtIP string The management IP of a device.


deviceTypename string The device type of a device.



1.3.2.Get the value of a device attribute

Use this API to get the value of a specific attribute of a device.



GET /V1/CMDB/Devices/Attributes Yes

Parameters

Name Description




Name Description

attributeName (query)

The name of the attribute that you want to get value. If not specified, return all attributes and their values.

hostname*required (query)

The hostname of a device.

Response


Attributes Object An attribute set. { "hostname": "BJ-R1", "attributes": { "mgmtIP": "172.24.10.2" }, "statusCode": 790200, "statusDescription": "Success." }

attributeName string The name of the attribute with its value returned.

hostname string The hostname of the returned device.



1.3.3.Get all interfaces of a device

Use this API to get all interfaces of a device.



GET /V1/CMDB/Interfaces Yes

Parameters

Name Description





Response



Interfaces list A list of interface names. { "statusCode": 790200, "statusDescription": "success", "interfaces": [ "Ethernet 0/1","Ethernet 0/2", "Ethernet 0/3" ] }



1.3.4.Get the value of an interface attribute

Use this API to get the value of a specific attribute of an interface.



GET /V1/CMDB/Interfaces/Attributes Yes

Parameters

Name Description





interfaceName*required (query)

The full name of an interface.


The attribute name of the interface that you want to get it value. If not specified, return all attributes and their values.

Response


hostname string The hostname of the returned device. { "statusCode": 790200, "statusDescription": "success", "hostname": "Bos-Core-1", "interfaceName": "XX",

interfaceName string The full name of the target interface.

interfaceAttributeValue string The returned attribute value.




"interfaceAttributeValue": "XX" }


Applicable Interface Attributes

Attribute Name Display Name in Device Details Pane Description

mibIndex MIB Index The MIB index of an interface.

bandwidth Bandwidth The bandwidth of an interface.

speed Speed The speed of an interface.

duplex Duplex The duplex of an interface.

intfStatus Live Status The state of an interface.

macAddr MAC Address The MAC address of an interface.

descr Description The description of an interface.

routingProtocol Routing Protocol The routing protocol configured on an interface.

multicastMode Multicasting Mode The multicasting mode of an interface.

mplsVrf MPLS VRF The name of the VRF configured on an interface.

mplsVpn MPLS VPN The MPLS VPN configured on an interface.

inAclName Inbound ACL The inbound ACL of an interface.

outAclName Outbound ACL The outbound ACL of an interface.

mode Switchport Mode The switchport mode of an interface.

vlan VLAN The VLAN number that an interface belongs to.

trunkNativeVlan Native VLAN The native VLAN of an interface as a switch port.

trunkEncapsulation Trunk Encapsulation The trunk encapsulation protocol of an interface as a trunk port.


1.3.5.Get all modules of a device

Use this API to get all modules of device specified by hostname.



GET /V1/CMDB/Modules Yes

Parameters

Name Description





Response


Modules list A list of all modules. { "statusCode": 790200, "statusDescription": "success", "modules": [ "module1","module2", "module3" ] }



1.3.6.Get the value of a module attribute

Use this API to get the value of a specific attribute of a module.



GET /V1/CMDB/Modules/Attributes Yes

Parameters


Name Description



moduleName*required (query)

The module name of a device.




The name of the attribute that you want to get it value. If not specified, return all attributes and their values.

Response


hostname string The hostname of the returned device. { "statusCode": 790200, "statusDescription": "success", "hostname": "Bos-Core-1", "attributeName": "XX", "moduleAttributeValue": "XX" }

attributeName string The name of the attribute.

moduleAttributeValue integer The value of the attribute.



1.3.7.Get the neighbors of a device by topology type

Use this API to get specific neighbors of a device according to the specified topology type.



GET /V1/CMDB/Topology/Devices/Neighbors Yes

Parameters

Name Description






Name Description

topoType*required (query)

Specify the topology type of the neighbors to be returned, such as L2_Topo_Type, L3_Topo_Type, Ipv6_L3_Topo_Type, and VPN_Topo_Type.

Response


neighbors list A list of returned neighbors. { "statusCode": 790200, "statusDescription": "success", "neighbors": [ { "hostname": "Bos-Core1", "interface": "FastEthernet0/1 172.24.32.226/28" } ]

hostname string The hostname of the neighbor device.

interface string The name of the neighbor interface.



1.3.8.Get the connected switch ports of an end system

Use this API to get the connected layer 2 switch ports of an end system.



GET /V1/CMDB/Topology/Devices/{ip}/ConnectedSwitchPort Yes

Parameters

Name Description



ip*required (path)

The IP address of a device interface.

Response



hostname list The hostname of the device that the end system connects to.

{ "statusCode": 790200, "statusDescription": "success", "hostname": "Bos-SW", "interface": "Ethernet 0/1" }

interface string The interface that the end system connects to.



1.3.9.Get device configuration

Use this API to get the configuration of a device.



GET /V1/CMDB/DataEngine/DeviceData/Configuration Yes

Parameter

Name Description




The hostname of the device that you want to get the configuration.

Response


configuration string The full context of the configuration of the device.

{'configuration': '!\r\n! This config file is generated via SNMP\r\n!\r\n! vendor,model,sysoid:**Cisco**2611**1.3.6.1.4.1.9.1.186**\r\n!\r\n hostname NY_POPP\r\n!\r\n\r\n\r\n interface Ethernet0/0\r\n description "Con-Catalyst 3/13"\r\n ip address 172.24.31.65 255.255.255.192\r\n!\r\n\r\n interface Tu2147483647\r\n description DMVPN shutdown Interface testing\r\n

time string The last update time of the device configuration.





ip address 172.16.33.4 255.255.255.248\r\n!\r\n\r\n', 'time': '2018-07-17T08:55:28Z', 'statusCode': 790200, 'statusDescription': 'Success.'}

1.4. Device Management

Use the following APIs to get devices and device data, add devices to a domain or remove devices from a domain.

Get devices by IP addresses

Get devices in a device group

Get the Front Server of a device

Remove devices from a domain in batch

1.4.1.Get devices in a device group

Use this API to get the devices in a device group.



GET /V1/CMDB/Devices/GroupDevices/{groupName} Yes

Parameters

Name Description



groupName*required (path)

The name of a device group.

Response



devices list A list of devices. { "devices": [ { "id": "967cadf3-f4e3-4714-97e8-a9ead6320057", "mgmtIP": "10.10.0.16", "hostname": "BST-POP1" } ] }

id string The device ID.

mgmtIP string The management IP address of the returned device.

hostname string The hostname of returned device.

1.4.2.Get the Front Server of a device

Use this API to get the front server associated with a device.



GET /V1/CMDB/Devices/{hostname}/FrontServer Yes

Parameters

Name Description



hostname*required (path)


Response


alias string The alias of the Front Server. { "alias": "Front Server Alias", "ipOrHostname": "Bos-Core", "statusCode": 790200, "statusDescription": "success" }

ipOrHostname string The IP address or name of the Front Server.

statusCode string The returned status code of executing the API.



1.4.3.Remove devices from a domain in batch

Use this API to remove a device from a domain using a list of hostnames or IPs.



DELETE /V1/CMDB/Devices Yes

Parameters

Name Description




The body must contain one of the following two parameters:

IPs (list): a list of management IP addresses of the target devices.

hostnames (list): a list of hostnames of the target devices.

Response




1.4.4.Get device group list

Use this API to get all device group lists in a domain.



GET /V1/CMDB/DeviceGroups Yes

Parameters


Name Description


Place the token received from login.

Response


deviceGroups list A list of all accessible domains. { "deviceGroups": [ { "id":"8196020b-b223-4bc8-8178-ac4da95b1695", "name":"#BGP 64512", "type":2 }, { "id":"fbd027f2-24c9-4616-a6bd-62b7613b07e1", "name":"#BGP 65000", "type":2 }, { "id":"fcdb1b8b-bffd-478f-a914-e867f6a87f86", "name":"retest", "type":0 } ], "statusCode":790200, "statusDescription":"Success." }

id string The ID of a device group

name string The name of a device group

type integer The type of a device group.

0: Public

1: Private

2: System

1.5. Attribute Management

Use the following APIs to manage device and interface attributes, such as creating/deleting a customized attribute.

Create a customized device attribute

Set value for a specified device attribute

Delete a device attribute

Create a customized interface attribute

Set value for a specified interface attribute

Delete an interface attribute

Create a customized module attribute


Set value for a specified module attribute

Delete a module attribute

1.5.1.Create a customized device attribute

Use this API to create a customized device attribute for certain device types.



POST /V1/CMDB/Devices/Attributes Yes

Parameters

Name Description





attributeName*(string): the name of the attribute to be created.

attributeDisplayName (string): the display name of the attribute in Device Details pane of NetBrain system.

deviceTypeNames*(string): specify the device types that the created attribute applies to. If set to null, it will apply to all device types. See Device Type Name and ID for the available device types.

dataType*(string): the supported data types of the attribute, such as string.

subDataType (string): this parameter is only available to the attribute in list or table type.

isFullSearch*(boolean): set whether to use the property as an index in full scope search, including extended search and default search.

Example:

{ "attributeName": "newAttribute", "attributeDisplayName": "New Attribute", "deviceTypeNames": "null", "dataType": "string", "subDataType": "null", "isFullSearch": true }

Response





1.5.2.Set value for a specified device attribute

Use this API to set a value for a specified attribute of a device.



PUT /V1/CMDB/Devices/Attributes Yes

Parameters

Name Description





attributeName*(string): the name of the attribute to set value.

attributeValue*(string): the value to set for the attribute.

hostname*(string): the hostname of the device.

Example:

{ "attributeName": "loc", "attributeValue": "Boston", "hostname": "Bos-Core1" }

Response





1.5.3.Delete a device attribute

Use this API to delete an attribute of a device.



DELETE /V1/CMDB/Devices/Attributes/{attributeName} Yes

Parameters

Name Description



attributeName*required (path)

The name of the attribute that you want to delete.

Response


statusCode integer The returned status code of executing the API. { "statusCode": 790200, "statusDescription": "success" }


1.5.4.Create a customized interface attribute

Use this API to create a customized interface attribute for certain device types.



POST /V1/CMDB/Interfaces/Attributes Yes

Parameters


Name Description





attributeName*(string): the name of the interface attribute to be created.

attributeDisplayName (string): the display name of the attribute in the Device Details pane of NetBrain system.

deviceTypeNames*(string): specify the device types that the created attribute applies to. If set to null, it will apply to all device types. See Device Type Name and ID for the available device types.

interfaceType*(string): the interface type that the created attribute applies to, such as intfs (Layer 2 topology type interfaces), ipIntfs (IPv4 L3 topology type interfaces), and ip6Intfs (IPv6 L3 topology type interfaces).



isFullSearch*(boolean): set whether to use the property as an index in full scope search, including extended search and default search.

Example:

{ "InterfaceType": "ipIntfs ", "attributeName": "newAttribute", "attributeDisplayName": "New Attribute", "deviceTypeNames": "null", "dataType": "string", "subDataType": "null", "isFullSearch": true }

Response




1.5.5.Set value for a specified interface attribute

Use this API to set a value for a specified attribute of an interface.




PUT /V1/CMDB/Interfaces/Attributes Yes

Parameters

Name Description








interfaceName*(string): the full name of the interface.

Example:

{ "attributeName": "loc", "attributeValue": "Boston", "hostname": "Bos-Core1", "interfaceName": "Ethernet0/1" }

Response




1.5.6.Delete an interface attribute

Use this API to delete an attribute of an interface.



DELETE /V1/CMDB/Interfaces/Attributes Yes


Parameters

Name Description



attributeName*required (query)

The name of the attribute that you want to delete.

InterfaceType*required (query)

The interface type that the created attribute applies to, such as intfs (Layer 2 topology type interfaces), ipIntfs (IPv4 L3 topology type interfaces), and ip6Intfs (IPv6 L3 topology type interfaces).

Response




1.5.7.Create a customized module attribute

Use this API to create a customized module attribute for certain device types.



POST /V1/CMDB/Modules/Attributes Yes

Parameters

Name Description





attributeName*(string): the name of the module attribute to be created.

attributeDisplayName (string): the display name of the attribute in the Device Details pane of NetBrain system.

deviceTypeNames*(string): specify the device types that the created attribute applies to. If set to null, it will apply to all device types. See Device Type Name and ID for available device types.



Name Description


isFullSearch*(boolean): set whether to use the attribute as an index in full scope search, including extended search and default search.

Example:

{ "attributeName": "newAttribute", "attributeDisplayName": "New Attribute", "deviceTypeNames": "null", "dataType": "string", "subDataType": "null", "isFullSearch": true }

Response




1.5.8.Set value for a specified module attribute

Use this API to set a value for a specified attribute of a module.



PUT /V1/CMDB/Modules/Attributes Yes

Parameters

Name Description








Name Description


moduleName*(string): the full name of the module.

Example:

{ "attributeName": "", "attributeValue": "Boston", "hostname": "Bos-Core1", "moduleName": "slot1" }

Response




1.5.9.Delete a module attribute

Use this API to delete an attribute of a module.



DELETE /V1/CMDB/Modules/Attributes Yes

Parameters

Name Description



body*required (body)


attributeName: the name of the attribute that you want to delete.

Response





1.6. Site Information

Use the following APIs to get the information of a site:

Get the basic information of a site

Get child sites under a specific site

Get devices in a specific site

1.6.1.Get the basic information of a site

Use this API to get the basic information of a site, such as a site ID and type.



GET /V1/CMDB/Sites/SiteInfo Yes

Parameters

Name Description



sitePath*required (query)

The full path of a site, such as My Network/NA/US.

Response


siteInfo object An object with the basic information of a site.

{ "siteInfo": [



siteId string The site ID. { "siteId": "1da4fda8-5d04-491b-8bb0-2e9abb989a60", "sitePath": "My Network/NA/US", "isContainer": true, "siteType": 0 } ] }

sitePath string The full path of a site.

isContainer bool Whether a site is container site.

siteType integer The type of a site:

0: root

1: container site,

2: leaf site

1.6.2.Get child sites of a specific site

Use this API to get all child sites of a specified site.



GET /V1/CMDB/Sites/ChildSites Yes

Parameters

Name Description





siteId (query)

The site ID.

Response


siteInfo list A list of all child sites. { "siteInfo": [ { "siteId": "1da4fda8-5d04-491b-8bb0-2e9abb989a60",

siteId string The site ID.

sitePath string The full path of a site.



siteType integer The type of a site.

0: root site

1: container site

2: leaf site

"sitePath": "My Network/NA/US", "isContainer": true, "siteType": 0 } ] }

isContainer bool Whether it is a container site.

1.6.3.Get devices in a specific site

Use this API to get all devices in a site.



GET /V1/CMDB/Sites/Devices Yes

Parameters

Name Description





Response


devices object An object with all devices in a site. { "devices": [ { "id": "7d47c791-84cb-4bdb-9d2c-abbfafe71b2e", "mgmtIP": "10.10.7.253", "hostname": "GW2Lab", "deviceTypeName": "Cisco IOS Switch" }

Id string The ID of a device

mgmtIP string The management IP of a device.




] }

1.7. Site Modification

Use the following APIs to modify the information of a site.

Create a transaction to start site modification

Remove a site transaction

Keep transaction alive

Create a parent site

Create a leaf site

Create sites

Delete a site

Add devices to a site

Replace devices in a site

Remove devices from a site

Commit modifications to rebuild a site

Use Flow to Modify a Site

Different from the usage of other APIs, the use of the Site Modification APIs needs to follow a certain use flow.

Example: Create a site and assign some devices to the site.

1. Start a transaction to start the modification.

2. Create a site.

3. Assign devices to the site.

4. Send heartbeat calls to maintain control of the transaction in the idle state of a transaction.

5. Commit changes and rebuild sites.


1.7.1.Create a transaction to start site modification

Use this API to create a transaction to start the site modification. Every time you want to change sites via APIs, you

first need to start a transaction.



POST /V1/CMDB/Sites/Transactions Yes

Parameters

Name Description



Response




1.7.2.Remove a site transaction

Use this API to remove a transaction.



DELETE /V1/CMDB/Sites/Transactions Yes

Parameters


Name Description



Response




1.7.3.Keep transaction alive

Use this API to keep control over a transaction throughout the process of site modification. Control over the transaction is extended by 30 seconds every time when one of the following operations is sent:

Create/delete site

Add/replace/delete devices from site

Send heartbeat call

If none of the above calls are made after 30 seconds, the transaction would be in the unlocked state. In the unlocked state, if another user opens a new transaction, your transaction would be discarded, and the new user will have control over modifying the site.



POST /V1/CMDB/Sites/Transactions/Heartbeat Yes

Parameters

Name Description



Response





1.7.4.Create a parent site

Use this API to create a parent site.



POST /V1/CMDB/Sites/Parent Yes

Parameters

Name Description





sitePath* (string): the full path of a site, such as My Network/Site1/Boston.

Response




1.7.5.Create a leaf site

Use this API to create a leaf site.




POST /V1/CMDB/Sites/Leaf Yes

Parameters

Name Description






Response




1.7.6.Create sites

Use this API to create multiple sites. A site will be created as a parent if the site does not have a parent site in the

current system.



POST /V1/CMDB/Sites Yes

Parameters

Name Description






isContainer* (bool): specify whether the site to be added is a container site.


Name Description

Example:

{ "sites": [ { "sitePath": "string", "isContainer": true }, { "sitePath": "string", "isContainer": false }, ] }

Response




1.7.7.Delete a site

Use this API to delete a site.



DELETE /V1/CMDB/Sites Yes

Parameters

Name Description




The full path of the site to be deleted.


Response




1.7.8.Add devices to a site

Use this API to add devices to a site.



POST /V1/CMDB/Sites/Devices Yes

Parameters

Name Description





sitePath* (string): the full path of the site that you want to add devices to.

Devices* (list): the devices to be added.

Example:

{ "sitePath": "XXXXXXX", "Devices": [ "Bos-Core1" ] }

Response





1.7.9.Replace devices in a site

Use this API to empty all devices in a site and add new devices to the site.



PUT /V1/CMDB/Sites/Devices Yes

Parameters

Name Description





sitePath* (string): the full path of a site.

Devices*(list): the devices to be added.

Example:


Response




1.7.10. Remove devices from a site

Use this API to remove devices from a site.




DELETE /V1/CMDB/Sites/Devices Yes

Parameters

Name Description





sitePath* (string): the full path of a site.

Devices* (list): the devices to be deleted.

Example:


Response




1.7.11. Commit modifications to rebuild a site

Use this API to commit all site change operations and rebuild sites.



PUT /V1/CMDB/Sites/Transactions Yes

Parameters


Name Description



rebuildSite*required (body)

(bool) Choose whether to rebuild sites.

Response




1.8. Path

Use the following APIs to calculate path and view results:

Calculate a Path

Get Path Calculation Result

Get the gateway information of a device

Stop a path

Get path calculation status

1.8.1.Calculate a Path

Use this API to calculate a path between two endpoints. The result will be returned in the form of a path ID, and you can use the path ID in the Get Path Calculation Result as the input parameter to get each hop information of

the path.



POST /V1/CMDB/Path/Calculation Yes

Parameters


Name Description





sourceIP*(string): input the IP address of the source device.

sourcePort (integer): specify the source protocol port, such as 23 for telnet. This parameter can be null.

sourceGwIP* (string): specify the gateway for path calculation.

o sourceGwDevice*: the hostname of the gateway device.

o sourceGwIntf*: the name of the gateway interface.

destIP*(string): input the IP address of the destination device.

destPort (integer): specify the destination protocol port, such as 23 for telnet. This parameter can be null.

pathAnalysisSet* (integer): specify the path type to calculate.

o 1: L3 Path

o 2: L2 Path

o 3: L3 Active Path

protocol* (integer): specify the application protocol, such as 4 for IPv4, and 6 for TCP.

isLive (integer): specify data used to calculate the path.

o 0: use data from the current baseline.

o 1: use data via live access.

Example:

{ "sourceIP": "10.10.3.253", "sourcePort": 0, "sourceGwIP": "10.10.3.253", "sourceGwDev": "GW2Lab", "sourceGwIntf": "GigabitEthernet0/0.10", "destIP": "172.24.32.225", "destPort": 0, "pathAnalysisSet": 1, "protocol": 4, "isLive": 1 }

Response


taskId string The ID of the task. { "taskId": "string", "statusCode": 790200, "statusDescription": "success" }




1.8.2.Get Path Calculation Result

Use this API to get the hop information of a path calculated through the Calculate a Path API.



GET /V1/CMDB/Path/Calculation/{taskID}/Result Yes

Parameters

Name Description



taskID*required (path)

The task ID returned in the Calculate a Path API.

Response



{ "statusCode": 790200, "statusDescription": "success", "hopList": [ { "hopId": "string", "srcDeviceName": "string", "inboundInterface": "string", "mediaName": "string", "dstDeviceName": "string", "outboundInterface": "string", "nextHopIdList": [ "7a09854d-1d87-4656-8556-a7b142fccb75" ] } ] }


hopList list A list of hops along a path.

hopId string The ID of a hop.

srcDeviceName string The hostname of the source device.

inboundInterface string The name of the inbound interface.

mediaName string The media name.

dstDeviceName string The hostname of the destination device.

outboundInterface string The name of the outbound interface.

nextHopIdList list A list of the IDs of next hops.


1.8.3.Get the gateway information of a device

Use this API to get the gateway information of a device based on IP or hostname.



GET /V1/CMDB/Path/Gateways Yes

Parameters

Name Description



ipOrHost*required (query)

The IP or hostname of a device.

Response


gatewayList list A list of returned gateway devices. The list contains the following subparameters:

ip (string): the IP address of a gateway.

devName (string): the hostname of a gateway.

IntfName (string): the name of the gateway interface.

{ "statusCode": 790200, "statusDescription": "success", "gatewayList": [ { "ip": "string", "devName": "string", "intfName": "string" } ] }



1.8.4.Stop a path

Use this API to stop a path in the calculation.




Post /V1/CMDB/Path/Calculation/Stop Yes

Parameters

Name Description



taskId*required (query)


Response



{ "result": true, "statusCode": 790200, "statusDescription": "Success." }


result bool The result of stopping a path.

1.8.5.Get path calculation status

Use this API to get the status of a path.



GET /V1/CMDB/Path/{taskID}/Status Yes

Parameters

Name Description



taskId*required (query)


Response




{ "statusCode":790200, "statusDescription":"success", "result":{ "resultCode":1, "resultDescription":"Running" } }


resultCode integer The status code of a path.

0: Initialized

1: Running

2: Succeeded

3: Failed

4: Canceled

resultDescription string The explanation of the result code.

1.9. System Management

Use the following APIs to manage your system, such as adding, updating and updating tenants and domains.

Add a tenant

Update a tenant

Delete a tenant

Assign users to a tenant

Add a domain

Update a domain

Delete a domain

Assign users to a domain

Remove users from a domain

Add a role

Update a role

Delete a role

1.9.1.Add a tenant

Use this API to add a tenant.




POST /V1/CMDB/Tenants Yes

Parameters

Name Description





tenantName*(string): the name of the tenant to be created.

description (string): the description of the tenant.

maximumNodes*(integer): the maximum licensed node count that the tenant owns. The number must be greater than 0.

maximumPorts (integer): the maximum number of SDN ports that the tenant owns.

maxinumCPU (integer): the maximum number of SDN CPU processors that the tenant owns.

Example:

{ "tenantName": "TenantName", "description": "Description", "maximumNodes": "5" }

Response


tenantId string The ID of the tenant. { "statusCode": 790200, "statusDescription": "string", "tenantId": "3e75247a-309c-4231-96a5-823b6cb1e78d" }


statusDescription

string The explanation of the status code.

1.9.2.Update a tenant

Use this API to update a tenant.




PUT /V1/CMDB/Tenants Yes

Parameters

Name Description





tenantId*(string): the name of the tenant that you want to update.

tenantName (string): the name of the tenant that you want to update.

description (string): the description of the tenant.

maximumNodes (integer): the maximum licensed node count that the tenant owns. The number must be greater than 0.



Example:

{ "tenantId": "4e75247a-309c-4231-96a5-823b6cb1e78d", "tenantName": "TenantName", "description": "Description", "maximumNodes": "5" }

Response




1.9.3.Delete a tenant

Use this API to delete a tenant.




DELETE /V1/CMDB/Tenants/{tenantId} Yes

Parameters

Name Description



tenantId*required (path)

The ID of the tenant that you want to delete.

Response




1.9.4.Assign users to a tenant

Use this API to assign users to a tenant.



POST /V1/CMDB/Tenants/Users Yes

Parameters

Name Description





tenantId*(string): the ID of the tenant that you assign users to.

users*(list): a list of users you want to assign. It contains two sub parameters:

o username*(string): the name of a user.

o isTenantAdmin(bool): determine whether the assigned user is an admin.


Name Description

Example:

{ "tenantId": "4e75247a-309c-4231-96a5-823b6cb1e78d", "users": { "username": "NetBrain", "isTenantAdmin": "NetBrain" } }

Response




1.9.5.Add a domain

Use this API to add a domain.



POST /V1/CMDB/Domains Yes

Parameters

Name Description





tenantId*(string): the ID of the tenant that the created domain belongs to.

domainName*(string): the name of the created domain.

description (string): the description of the domain.

maximumNodes*(integer): the maximum licensed node count that the domain owns. The number must be greater than 0.




Name Description

Example:

{ "tenantId": "4e75247a-309c-4231-96a5-823b6cb1e78d", "domainName": "domainName", "description": "Description", "maximumNodes": "5" }

Response


domainId string The ID of the domain. { "statusCode": 790200, "statusDescription": "string", "domainId": "5e75247a-309c-4231-96a5-823b6cb1e78d" }



1.9.6.Update a domain

Use this API to update a domain.



PUT /V1/CMDB/Domains Yes

Parameters

Name Description





domainId*(string): the name of the domain that you want to update.

domainName (string): the name of the domain that you want to update.

description (string): the description about the domain.

maximumNodes (integer): the maximum license nodes that the domain owns. The number must be greater than 0.


Name Description



Example:

{ "domainId": "5e75247a-309c-4231-96a5-823b6cb1e78d", "domainName": "TenantName", "description": "Description", "maximumNodes": "5" }

Response




1.9.7.Delete a domain

Use this API to delete a domain.



PUT /V1/CMDB/Domains/{domainId} Yes

Parameters

Name Description



domainId*required (path)

The ID of the domain that you want to delete.

Response





statusDescription string The explanation of the status code. { "statusCode": 790200, "statusDescription": "success" }

1.9.8.Assign users to a domain

Use this API to assign users to a domain.



POST /V1/CMDB/Domain/Users Yes

Parameters

Name Description





domainId*(string): the ID of the domain that you assign users to.

users*(list): a list of users you want to assign. It contains two sub parameters:

o username*(string): the name of a user.

o roles: the roles of a user, such as admin, guest, and engineer.

Example:

{ "domainId": "3e75247a-309c-4231-96a5-823b6cb1e78d", "users": { "username": "NetBrain", "roles": "guest" } }

Response





1.9.9.Remove users from a domain

Use this API to remove users from a domain.



DELETE /V1/CMDB/Domain/Users Yes

Parameters

Name Description





domainId*(string): the ID of the domain that you remove users from.

users*(list): a list of users you want to remove.

Example:

{ "domainId": "3e75247a-309c-4231-96a5-823b6cb1e78d", "users": { "user1","user2" " } }

Response





1.9.10. Add a role

Use this API to add a role and grant privileges to the role.



POST /V1/CMDB/Roles Yes

Parameters

Name Description





roleName*(string): the name of the role that you want to add.

description (string): the description of the role.

privileges (string): the privileges that the role owns.

Example:

{ "roleName": "Role Name", "description": "string", "privileges": "string" }

Response




1.9.11. Update a role

Use this API to update a role and its privileges.




PUT /V1/CMDB/Roles Yes

Parameters

Name Description





newRoleName (string): a new name of the role. No change will be made if newRoleName, description, and privileges fields are all null.

roleName*(string): the name of the role that you want to update.

description (string): the description of the role.

privileges (string): the privileges that the role owns.

Example:

{ "newRoleName": "Role Name", "roleName": "Role Name", "description": "string", "privileges": "string" }

Response




1.9.12. Delete a role

Use this API to delete a role.




DELETE /V1/CMDB/Roles/{Rolename} Yes

Parameters

Name Description



roleName*required (path)

The name of the role that you want to delete.

Response




1.9.13. Get role information

Use this API to get the information of a role.



Get /V1/CMDB/Roles Yes

Parameters

Name Description



roleName (query)

The name of the role. If null, return the information of all roles.

Response



roleData List A list of role information. It contains the following parameters:

roleName (string): the name of a role.

description (string): the description of a role.

privileges (list): the privileges of a role.

{ "statusCode": 790200, "statusDescription": "success", "RoleData": [ { 'roleName': "networkChangeApprover", 'newRoleName': None, 'description': ''Network Change Approver', 'privileges': None } ] }


statusDescription

string The explanation of the status code.

1.10. Topology Building

Use the following APIs to build or rebuild your network topology when the network changes:

Build L2 topology

Build L3 topology

Get the running status of a topology building task

1.10.1. Build L2 topology

Use this API to build or rebuild the Layer 2 topology for all network devices in a domain.



POST /V1/CMDB/Topology/Tasks/L2 Yes

Parameters

Name Description




Response


taskId string The task Id. It can be used to query task status.

{ "taskId": "string", "statusCode": 790200, "statusDescription": "success" }



1.10.2. Build L3 topology

Use this API to build or rebuild the Layer 3 topology for all network devices in a domain.



POST /V1/CMDB/Topology/Tasks/L3 Yes

Parameters

Name Description



Response


taskId string The task Id. It can be used to query task status.

{ "taskId": "string", "statusCode": 790200, "statusDescription": "success" }



1.10.3. Get the status of topology building

Use this API to get the status of an L2/L3 topology building task.




Get /V1/CMDB/Topology/Tasks/{task}/Status Yes

Parameters

Name Description



taskId*required (path)

The ID of a topology building task.

Response


status string The status of the topology building task. { "status": "finished", "statusCode": 790200, "statusDescription": "success" }



1.10.4. Get One-IP Table

Use this API to get all IP addresses in the same network segment.



Get /V1/CMDB/Topology/OneIPTable Yes

Parameters

Name Description



ip (string) (query)

The IP address that you want to return its One-IP Table items.


Name Description

If this parameter is specified, the API returns the One-IP table items that have the same IP and ignore the beginIndex and count parameters.

If null, the API returns all One-IP table items and the API uses the beginIndex and count parameters to return results.

beginIndex (int) (query)

Specify from which row to begin indexing data. For example, the begin is 0, and the API will return One-IP Table results starting from the first row. This parameter is required when the IP parameter is specified.

count (int) (query)

Specify the maximum number of returned data. This parameter is required when the IP parameter is specified.

Response


oneIPList List A list of One-IP items. { "statusCode": 790200, "statusDescription": "success", "OneIPList": [ { 'alias': "", 'descr': '"if&ipfor EIGRP"', 'devName': 'SanJose_Core', 'dns': 'SanJose_Core', 'interfaceName': 'Ethernet0/0', 'ip': '30.1.3.1', 'lanSegment': '30.1.3.0/24', 'mac': 'FCFB.FB8C.6288', 'portName': 'Ethernet0/0', 'serverType': 2, 'source': 'ARP Table', 'sourceDevice': 'SanJose_Core', 'switchName': 'NY_DIS_1', 'switchType': 2, 'updateTime': '2018-07-31', 'userFlag': 7, 'vendor': 'Cisco Systems'}, } ] }

ip string The IP address of an end system or device interface in a One-IP table item.

lanSegment string The LAN segment of the IP address.

mac string The MAC address that the IP corresponds to.

devName string The name of the device that the IP belongs to.

interfaceName

string The name of the interface that the IP belongs to.

switchName string The name of the switch that the IP connects to.

portName string The name of the switch port that the IP connects to

alias string The routing redundancy protocol that the interface of the IP configures, such as HSRP/GLBP/VRRP.

dns string The DNS of an IP.

sourceDevice string The source device that the IP is discovered from.

serverType string The type of the device that the IP belongs to.

switchType string The type of the switch that the IP connects to.



updateTime string The last update time of the One-IP Table item.

userFlag int The method to retrieve the IP.

0: Auto

1: Manual

5: CDP/LLDP table

6: MAC table

7: ARP table

9: Device Interface

source string The method to retrieve the IP, such as from MAC table.

vendor string The vendor of the device that the IP belongs to.

descr string The description of the switchport that the IP address connects to.

1.11. Network Settings

Use the following APIs to manage credentials in Network Settings.

Add network credentials

Edit network credentials

Delete network credentials

1.11.1. Add network credentials

Use this API to add a network credential.



POST /V1/CMDB/NetworkSettings Yes


Parameters

Name Description





privateKey (object): used to add a private key. It contains the following subparameters:

o alias* (string): the alias of the private key.

o keyName (string): the name of the private key.

o md5KeyContent (string): the MD5 content of the key.

o keyContent (string): the content of the key.

o passwordPhrase (string): the passphrase of the key.

jumpBox (object): used to add a jump box setting. It contains the following subparameters:

o alias* (string): the alias of the jump box.

o ipAddr (string): the IP address of the jump box.

o mode (int, mandatory): the access mode from the Front Server to the Jump box.

0: Telnet

1: SSH

2: SSH Public Key

o port (integer): the port of the access port such as 23 for telnet.

o username (string): the username to access the jumpbox. This parameter is mandatory only if the mode is 1 or 2.

o password (string): the password to access the jumpbox. This parameter is mandatory only if the mode is 1.

o keyName (string): the name of the SSH public key. This parameter is mandatory only if the mode is 2.

o loginPrompt (string): the login prompt to connect the jumpbox.

o passwordPrompt (string): the login password to connect the jumpbox.

o commandPrompt (string): the prompt to enter CLI command, such as >.

o yesNoPrompt (string): the prompt to save the SSH key.

o telnetCommand (string): configure a special command to access via Telnet when necessary. For example, telnet $(IP) $(PORT).

o SSHCommand(string): configure a special command to access via SSH when necessary. For example, ssh -l $(USERNAME) -p $(PORT) $(IP).

o cmd2 (string): the login command for the special command.

o cmd2PasswordPrompt (string): the login prompt to connect the jumpbox for the special command.

o cmd2Password (string): the login password to connect the jumpbox for the special command.


Name Description

o cmd2ModePrompt (string): the mode prompt for the special command.

o quitCmd (string): the quit command.

telnetInfo (object): used to add telnet/SSH login credentials. It contains the following subparameters:

o alias* (string): the alias of telnet/SSH login credentials.

o username (string): the username of the non-privileged login.

o password (string): the password of the non-privileged login.

o cliMode (integer): the authentication method.

0: Telnet/SSH Password

2: SSH public key.

o keyName (string): the name of the SSH public key. This parameter is mandatory only if the cliMode parameter is 2.

privilegeInfo (object): used to add privileged credentials.

o alias* (string): the alias of the privileged credentials.

o username (string): the username of the privileged login.

o password (string): the password of the privileged login.

snmpInfo (object): used to add SNMP credentials.

o alias* (string): the alias of the SNMP credentials.

o snmpVersion (integer): the version of the SNMP string.

1: SNMP v1 and v2c

3: SNMP v3.

The other parameters are different based on SNMP versions.

• SNMP v1 and v2c: oroString (string) and SNMP read-only community string.

• SNMP v3: v3 information will be effective.

o roString (string): SNMP read-only community string.

o v3 (object): Settings if SNMP v3 is applied in snmpInfo.snmpVersion.

authMode (integer): the authentication mode of SNMP V3.

• 1: no authen no priv

• 2: auth no priv

• 3: auth priv

authPro (integer): the authentication method of SNMP V3. Effective when snmpInfo.v3.authMode is 2 or 3.

• 1: md5

• 2: SHA

encryptPro (integer): the encryption method. Effective when snmpInfo.v3.authMode is 3.

• 1: DES

• 2: AES,

• 3: AES192,

• 4: AES256.


Name Description

username (string): the username to access the network devices.

contextName (string): the context name of authentication privilege.

authPassword (string): the authentication password. This field is effective when the authMode is 2 or 3.

encryptPassword (string): the encryption password. This field is required when the authMode is 3.

Example:

{ "privateKey": { "alias": "string", "keyName": "string", "md5KeyContent": "string", "keyContent": "string", "passwordPhrase": "string" }, "jumpBox": { "alias": "string", "ipAddr": "string", "mode": 0, "port": 0, "username": "string", "password": "string", "KeyName": "string", "loginPrompt": "string", "passwordPrompt": "string", "commandPrompt": "string", "yesNoPrompt": "string", "telnetCommand": "string", "SSHCommand": "string", "cmd2": "string", "cmd2PasswordPrompt": "string", "cmd2Password": "string", "cmd2ModePrompt": "string", "quitCmd": "string" }, "telnetInfo": { "alias": "string", "userName": "string", "password": "string", "cliMode": 0, "keyName": "string" }, "privilegeInfo": { "alias": "string", "userName": "string", "password": "string" }, "snmpInfo": { "alias": "string",


Name Description

"snmpVersion": 0, "roString": "string", "v3": { "authMode": 0, "authPro": 0, "encryptPro": 0, "userName": "string", "contextName": "string", "authPassword": "string", "encryptPassword": "string" } } }

Response




1.11.2. Edit network credentials

Use this API to edit a network credential.



PUT /V1/CMDB/NetworkSettings Yes

Parameters

Name Description





privateKey (object): used to add a private key. It contains the following subparameters:


Name Description

o alias* (string): the alias of the private key.

o keyName (string): the name of the private key.

o md5KeyContent (string): the MD5 content of the key.

o keyContent (string): the content of the key.

o passwordPhrase (string): the passphrase of the key.

jumpBox (object): used to add a jump box setting. It contains the following subparameters:

o alias* (string): the alias of the jump box.

o ipAddr (string): the IP address of the jump box.

o mode (int, mandatory): the access mode from the Front Server to the Jump box.

0: Telnet

1: SSH

2: SSH Public Key

o port (integer): the port of the access port such as 23 for telnet.

o username (string): the username to access the jumpbox. This parameter is mandatory only if the mode is 1 or 2.

o password (string): the password to access the jumpbox. This parameter is mandatory only if the mode is 1.

o keyName (string): the name of the SSH public key. This parameter is mandatory only if the mode is 2.

o loginPrompt (string): the login prompt to connect the jumpbox.

o passwordPrompt (string): the login password to connect the jumpbox.

o commandPrompt (string): the prompt to enter CLI command, such as >.

o yesNoPrompt (string): the prompt to save the SSH key.

o telnetCommand (string): configure a special command to access via Telnet when necessary. For example, telnet $(IP) $(PORT).

o SSHCommand(string): configure a special command to access via SSH when necessary. For example, ssh -l $(USERNAME) -p $(PORT) $(IP).

o cmd2 (string): the login command for the special command.

o cmd2PasswordPrompt (string): the login prompt to connect the jumpbox for the special command.

o cmd2Password (string): the login password to connect the jumpbox for the special command.

o cmd2ModePrompt (string): the mode prompt for the special command.

o quitCmd (string): the quit command.

telnetInfo (object): used to add telnet/SSH login credentials. It contains the following subparameters:

o alias* (string): the alias of telnet/SSH login credentials.


Name Description

o username (string): the username of the non-privileged login.

o password (string): the password of the non-privileged login.

o cliMode (integer): the authentication method.

0: Telnet/SSH Password

2: SSH public key.

o keyName (string): the name of the SSH public key. This parameter is mandatory only if the cliMode parameter is 2.

privilegeInfo (object): used to add privileged credentials.

o alias* (string): the alias of the privileged credentials.

o username (string): the username of the privileged login.

o password (string): the password of the privileged login.

snmpInfo (object): used to add SNMP credentials.

o alias* (string): the alias of the SNMP credentials.

o snmpVersion (integer): the version of the SNMP string.

1: SNMP v1 and v2c

3: SNMP v3.

The other parameters are different based on SNMP versions.

• SNMP v1 and v2c: oroString (string) and SNMP read-only community string.

• SNMP v3: v3 information will be effective.

o roString (string): SNMP read-only community string.

o v3 (object): Settings if SNMP v3 is applied in snmpInfo.snmpVersion.

authMode (integer): the authentication mode of SNMP V3.

• 1: no authen no priv

• 2: auth no priv

• 3: auth priv

authPro (integer): the authentication method of SNMP V3. Effective when snmpInfo.v3.authMode is 2 or 3.

• 1: md5

• 2: SHA

encryptPro (integer): the encryption method. Effective when snmpInfo.v3.authMode is 3.

• 1: DES

• 2: AES,

• 3: AES192,

• 4: AES256.

username (string): the username to access the network devices.

contextName (string): the context name of authentication privilege.

authPassword (string): the authentication password. This field is effective when the authMode is 2 or 3.

encryptPassword (string): the encryption password. This field is required when the authMode is 3.


Name Description

Example:

{ "privateKey": { "alias": "string", "keyName": "string", "md5KeyContent": "string", "keyContent": "string", "passwordPhrase": "string" }, "jumpBox": { "alias": "string", "ipAddr": "string", "mode": 0, "port": 0, "username": "string", "password": "string", "KeyName": "string", "loginPrompt": "string", "passwordPrompt": "string", "commandPrompt": "string", "yesNoPrompt": "string", "telnetCommand": "string", "SSHCommand": "string", "cmd2": "string", "cmd2PasswordPrompt": "string", "cmd2Password": "string", "cmd2ModePrompt": "string", "quitCmd": "string" }, "telnetInfo": { "alias": "string", "userName": "string", "password": "string", "cliMode": 0, "keyName": "string" }, "privilegeInfo": { "alias": "string", "userName": "string", "password": "string" }, "snmpInfo": { "alias": "string", "snmpVersion": 0, "roString": "string", "v3": { "authMode": 0, "authPro": 0, "encryptPro": 0, "userName": "string", "contextName": "string",


Name Description

"authPassword": "string", "encryptPassword": "string" } } }

Response




1.11.3. Delete network credentials

Use this API to delete a specific network setting.



DELETE /V1/CMDB/NetworkSettings Yes

Parameters

Name Description





privateKey (object): the private keys. Input the alias of the private key:

o alias* (string): the alias of the private key that you want to delete.

jumpBox (object): the jump box settings. Input the alias of the jump box:

o alias* (string): the alias of the jump box that you want to delete.

telnetInfo (object): the telnet/SSH login credentials. Input the alias of the telnet/SSH login credentials:

o alias* (string): the alias of telnet/SSH login credentials that you want to delete.


Name Description

privilegeInfo (object): the privilege credentials. Input the alias of the privilege credentials:

o alias* (string): the alias of the privilege credentials that you want to delete.

snmpInfo (object): the SNMP credentials. Input the alias of the SNMP credentials:

o alias* (string): the alias of the SNMP credentials that you want to delete.

Example:

{ "privateKey": { "alias": "string" }, "jumpBox": { "alias": "string" }, "telnetInfo": { "alias": "string" }, "privilegeInfo": { "alias": "string" }, "snmpInfo": { "alias": "string" } }

Response




1.12. Map

Use the following API to export a map to local:

Export a map

Delete a map


1.12.1. Export a map

Use this API to export a map into .xmap or .visio from a NetBrain map URL.



GET /V1/CMDB/Maps Yes

Parameters

Name Description



url*required (query)

The URL of the map that you want to export.

format*required (query)

The format of the exported map file, such as "xmap", "visio".

pages (query)

The name of the map page that you want to export.

Response


fileData object Byte stream of xmap in specified format. { "fileData": "string", "statusCode": 790200, "statusDescription": "success" }



1.12.2. Delete a map

Use this API to delete a map from the current domain.




DELETE /V1/CMDB/Maps Yes

Parameters

Name Description



url*required (query)

The URL of the map that you will delete.

Response




1.12.3. Get the file list

Use this API to get the file lists contained in the Public folder of your NetBrain Files.



POST /V1/CMDB/Files/ Yes

Parameters


Name Description



Body*required (body)


folderid (string): The ID of the folder that you want to get its files. Return the root folder (Public) if folderid is null.

fileTypes*(array): the file types you want to get. There are three file types:

0: Folder

11: Map

21: Dashboard

Example:

{ "folderId": "", "fileTypes": [ 0, 11 ,21] }

Response


items list A list of folders and files. { "items": [ { "id":"ad09aa07-b31d-4f42-a0aa-319697825b09", "name":"Public/Site Maps", "type":0 }, { "originalId":"75ff3cdf-dff4-48c6-a736-7a86e4374a29", "id":"2a19165f-a4a5-4488-ac5d-acdf9e287ed6", "name":"Public/New Folder/New Folder/New Map", "type":11 }, { "originalId":"d2650deb-5276-44cb-be21-43e2b129380a", "id":"a84cdca3-3710-47b1-b037-665e38fd6d08", "name":"Public/New Folder(1)/New Map", "type":11 } ], "statusCode":790200,

id string The ID of a folder in the Files tree.

name string The name of a file.

originalId string For the Map and Dashboard types only. The ID of a specific dashboard or file.

type integer The type of a file.

0: Folder

11: Map

21: Dashboard



"statusDescription":"Success." }

1.12.4. Get device groups

Use this API to get all device group lists in a domain.



GET /V1/CMDB/DeviceGroups Yes

Parameters

Name Description



Response


deviceGroups list A list of all accessible domains. { "deviceGroups": [ { "id":"8196020b-b223-4bc8-8178-ac4da95b1695", "name":"#BGP 64512", "type":2 }, { "id":"fbd027f2-24c9-4616-a6bd-62b7613b07e1", "name":"#BGP 65000", "type":2 }, { "id":"fcdb1b8b-bffd-478f-a914-e867f6a87f86", "name":"retest", "type":0 } ],

id string The ID of a device group

name string The name of a device group

type integer The type of a device group.

0: Public

1: Private

2: System



"statusCode":790200, "statusDescription":"Success." }

1.13. Benchmark

Use the following APIs to manage benchmark tasks in a domain.

Add a benchmark task

Update a benchmark task

Delete a benchmark task

Run a benchmark task immediately

Get the status of a benchmark task

Get the execution history of a benchmark task

1.13.1. Add a benchmark task

Use this API to add a benchmark task. The option for data to be retrieved in this task is ‘Built-in Live Data’ which

you can see from benchmark UI.


Method URL Authentication

POST /V1/CMDB/Benchmark/Tasks Yes

Parameters

Name Description





taskName* (string): the name of the task.

description (string): the description of the task.

startDate* (string): the date when the task starts to run. The standard time format is required. For example, 2017-07-13, or 2017/07/13.


Name Description

schedule* (object): the schedule to run the task. The following subparameters are included in this object:

o frequency* (string): the frequency to run the task. It includes ”once”, “hourly”,” daily”, “weekly” and “monthly” options.

o interval (integer): the interval to run the task. This field is only valid for “hourly”,” daily”, and “weekly” options and the default value is 1, such as every 1 hour, 1 week.

o startTime* (string): the time to run the task. The time format is full UTC time. For example, 2017/7/11 16:20:20.

Note: Set the time according to your IIS server timezone.

o weekday (integer): the day of the week to run the task. This field is only valid when the frequency is weekly.

0: Sunday

1: Monday

2: Tuesday

3: Wednesday

4: Thursday

5: Friday

6: Saturday

o dayOfMonth (integer): which day of a month to run the task. This field is only valid when the frequency is monthly. The default is 1.

o Months: which month to run the task. This field is optional and only valid when the frequency is monthly. The default value is 12.

deviceScope* (string): the devices included in this task. The device scope includes three types - 'all’, ‘deviceGroup’ and 'site’.

o For the deviceGroup type, the scope should be the array of full path of deviceGroups. For example, Public/xxx, Private/xxx, or System/xxx.

o For the site type, the scope should be the array of full path of sites. For example, My Network/Unnamed-site1/Site1.

limitRunMins (string): the time used to retrieve the data. When it reaches the specified time, the task will stop retrieving more data.

cliCommands (string): the customized CLI command to retrieve data. For example, show version.

isBuildIPv4L3Topo (bool): determine whether to build IPv4 L3 topology. The default value is false.


isBuildL2Topo (bool): determine whether to build L2 topology. The default value is false.

isBuildIPsecVPNTopology (bool): determine whether to build IPsecVPN topology. The default value is false.

isRecalculateDynamicDeviceGroups (bool): determine whether to recalculate dynamic device groups. The default value is false.


Name Description

isRecalculateSite (bool): determine whether to rebuild sites. This field is optional and the default value is false.

isRecalculateMPLSVirtualRouteTables (bool): determine whether to recalculate MPLS Virtual Route Table. The default value is false.

isbuildDefaultDeviceDataView (bool): determine whether to build default device data view. The default value is false.

isEnable (bool): determine whether to enable the task. The default value is true.

Response




1.13.2. Update a benchmark task

Use this API to update a benchmark task.



PUT /V1/CMDB/Benchmark/Tasks Yes

Parameters

Name Description





taskName* (string): the name of the task.

description (string): the description of the task.

startDate* (string): the date when the task starts to run. The standard time format is required. For example, 2017-07-13, or 2017/07/13.

schedule* (object): the schedule to run the task. The following subparameters are included in this object:


Name Description

o frequency* (string): the frequency to run the task. It includes ”once”, “hourly”,” daily”, “weekly” and “monthly” options.

o interval (integer): the interval to run the task. This field is only valid for “hourly”,” daily”, and “weekly” options and the default value is 1, such as every 1 hour, 1 week.

o startTime* (string): the time to run the task. The time format is full UTC time. For example, 2017/7/11 16:20:20.

Note: Set the time according to your IIS server timezone.

o weekday (integer): the day of the week to run the task. This field is only valid when the frequency is weekly.

0: Sunday

1: Monday

2: Tuesday

3: Wednesday

4: Thursday

5: Friday

6: Saturday

o dayOfMonth (integer): which day of a month to run the task. This field is only valid when the frequency is monthly. The default is 1.

o Months: which month to run the task. This field is optional and only valid when the frequency is monthly. The default value is 12.

deviceScope* (string): the devices included in this task. The device scope includes three types - 'all’, ‘deviceGroup’ and 'site’.

o For the deviceGroup type, the scope should be the array of full path of deviceGroups. For example, Public/xxx, Private/xxx, or System/xxx.

o For the site type, the scope should be the array of full path of sites. For example, My Network/Unnamed-site1/Site1.

limitRunMins (string): the time used to retrieve the data. When it reaches the specified time, the task will stop retrieving more data.

cliCommands (string): the customized CLI command to retrieve data. For example, show version.



isBuildL2Topo (bool): determine whether to build L2 topology. The default value is false.

isBuildIPsecVPNTopology (bool): determine whether to build IPsecVPN topology. The default value is false.

isRecalculateDynamicDeviceGroups (bool): determine whether to recalculate dynamic device groups. The default value is false.

isRecalculateSite (bool): determine whether to rebuild sites. This field is optional and the default value is false.


Name Description

isRecalculateMPLSVirtualRouteTables (bool): determine whether to recalculate MPLS Virtual Route Table. The default value is false.

isbuildDefaultDeviceDataView (bool): determine whether to build default device data view. The default value is false.

isEnable (bool): determine whether to enable the task. The default value is true.

Response




1.13.3. Delete a benchmark task

Use this API to delete a benchmark task.



DELETE /V1/CMDB/Benchmark/Tasks/{task} Yes

Parameters

Name Description




The name of the benchmark task you want to delete.

Response





1.13.4. Run a benchmark task immediately

Use this API to run a benchmark task immediately.



POST /V1/CMDB/Benchmark/Tasks/{task}/Run Yes

Parameters

Name Description




The ID or name of the benchmark task you want to run.

Response




1.13.5. Get the status of a benchmark task

Use this API to get the status of a benchmark task.



GET /V1/CMDB/Benchmark/Tasks/{task}/Status Yes

Parameters

Name Description




Name Description


The ID or name of the benchmark task.

Response


taskStatus integer The status of the scheduled task. Possible values:

1: Unknown

0: Never run

2: Running

10: Succeeded


20: Failed


31: Automatically stopped due to timeout set by users or another system setting.

{ "taskStatus": 0, "statusCode": 790200, "statusDescription": "success" }



1.13.6. Get the run records of a benchmark task

Use this API to get the execution history of a benchmark task. One benchmark task can be executed many times,

periodically or manually by users. Each execution creates a run record.



GET /V1/CMDB/Benchmark/Tasks/{task}/Runs Yes

Parameters

Name Description




The ID or name of the benchmark task.


Response


runs object An object with the historical record of each run. Each execution creates a run record.

{ "runs": [ { "runId": "string", "startTime": "string", "endTime": "string", "status": 10, "isFinished": true, "isStopByUser": true } ], "statusCode": 790200, "statusDescription": "success" }

runId string The ID for every specific run.

startTime string The start time of a specific run.

endTime string The end time of a specific run.

status integer The status of a scheduled task. Possible values:

1: Unknown

0: Never run

2: Running

10: Succeeded


20: Failed


31: Automatically stopped due to timeout set by users or another system setting

isFinished bool Whether a scheduled task is finished.

isStopByUser bool Whether a scheduled task is manually stopped by users.



1.14. Tuning Devices

The Tuning Devices API allows you to start a tuning task to your network devices and get the result of the tuning.

Tune Devices

Get the results of tuning devices


1.14.1. Tune devices

Use this API to start a task of tuning devices.



POST /V1/CMDB/TuneDevices Yes

Parameters

Name Description




The parameter contains the following sub parameters:

isCheckPing (bool): whether to PING the IP of a device when tuning it.

isCheckSnmp (bool): whether to check SNMP access when tuning a device.

isCheckCliLogin (bool): whether to check Telnet/SSH access when tuning a device.

isCheckCliEnable (bool): whether to check Enable credentials when tuning a device.

hostnames (list): the devices that you want to tune. If null, all devices will be tuned.

Response


taskId string The task ID of tuning devices. This ID is used to get the results of the tuning task.

{ "taskId": "string", "statusCode": 790200, "statusDescription": "Success." }



1.14.2. Get the results of tuning devices

Use this API to get the results of tuning devices.




Get /V1/CMDB/TuneDevices Yes

Parameters

Name Description



taskId (string) (query)

The task ID of tuning devices.

begin (int) (query)

Specify from which row to begin indexing data. For example, the begin is 0, and the API will return tuning result starting from the first row. This parameter is required when the hostnames parameter is not specified.

count (int) (query)

Specify the maximum number of returned data. This parameter is required when the hostnames parameter is not specified.

hostnames (list) (query)

List all devices that need to return tuning result.

if this parameter is specified, the begin and count parameters are useless.

If not specified, use the begin and count to return tune results.

Response


devices list A list of devices that return tuning result. { "devices": [ { "deviceName": "string", "log": "string", "TuneState": { "Enable": "string", "Hostname": "string", "LiveHostname": "string", "Login": "string", "MgrIntf": "string", "MgrIp": "string", "Model": "string", "NetworkServer": "string", "Ping": "string", "SnmpRo": "string", "TelnetSSH": "string", "Vendor": "string" } } ], "statusCode": "200",

deviceName string The name of a tuned device.

log string The log of device tuning.

tuneState object The tune state.

enable string The result of logging into Enable mode.

hostname string The hostname of a tuned device.

liveHostname string The live hostname of a device.

login string The login result of a device.

mgrIntf string The management interface of a device.

mgrIp string The management IP of a device.

model string The model name of a device.

networkServer string The front sever name of a device.



ping string The ping result. "statusDescription": "Success" }

snmpRo string The SNMPRO information of a device

telnetSSH string The Telnet and SSH result of a device.

vendor string The vendor name of a device.

deviceName string The device name.

log string The log of tuning a device.



1.15. Users

Use the following APIs to manage user accounts.

Add users

Update users

Delete users

Get the usage report of users

Get user information

1.15.1. Add users

Use this API to create user accounts in the system.



POST /V1/CMDB/Users Yes

Parameters


Name Description





username* (string): the username to log into your NetBrain domain.

email* (string): the email address of the user.

firstName* (string): the first name of the user.

lastName* (string): the last name of the user.

password* (string): the login password. The allowed length is 6-128 characters.

authenticationType (integer): the authentication type for the user account.

o 1: Local

o 2: External

phoneNumber (string): the phone number of the user.

department (string): the department that the user belongs to.

description (string): the description of the account.

allowChangePassword (bool): determine whether to allow the user to change individual password.

deactivatedTime (string): specify the time when the account is expired.

isSystemAdmin (bool): determine whether to allocate system administrator role to the user.

tenants (object): specify a list of tenants for the user. Only required if the value of the isSystemAdmin parameter is false.

o tenantName (string): the tenant that the user can access.

o isTenantAdmin (bool): determine whether to allocate the tenant administrator role to the user. If false, you need to specify a domain for the user to access.

o allowCreateDomain (bool): determine whether to allow the user to create domains.

o domains (object): required only if the value of the isTenantAdmin parameter is false.

o domainName (string): the domain name.

o domainRoles(string): the role of the domain user. Specify a tenant for the user.

Example:

{ "username": NetBrain, "email": [email protected], "firstName": NetBrain, "lastName": NetBrain, "password": ******, "authenticationType": null, "phoneNumber": null, "department": null, "description": null, "allowChangePassword": null, "deactivatedTime": null, "isSystemAdmin": null, "tenants": null }


Response




1.15.2. Update users

Use this API to modify user information.



PUT /V1/CMDB/Users Yes

Parameters

Name Description





username* (string): the username to log into your NetBrain domain.

email* (string): the email address of the user.

firstName* (integer): the first name of the user.

lastName* (integer): the last name of the user.

password* (integer): the login password. The allowed length is 6-128 characters.

authenticationType (integer): the authentication type for the user account.

o 1: Local

o 2: External

phoneNumber (string): the phone number of the user.

department (string): the department that the user belongs to.

description (string): the description of the account.

allowChangePassword (bool): determine whether to allow the user to change individual password.

deactivatedTime (string): specify the time when the account is expired.

isSystemAdmin (bool): determine whether to allocate system administrator role to the user.


Name Description

tenants (object): specify a list of tenants for the user. Only required if the value of the isSystemAdmin parameter is false.

o tenantName (string): the tenant that the user can access.

o isTenantAdmin (bool): determine whether to allocate the tenant administrator role to the user. If false, you need to specify a domain for the user to access.

o allowCreateDomain (bool): determine whether to allow the user to create domains.

o domains (object): required only if the value of the isTenantAdmin parameter is false.

o domainName (string): the domain name.

o domainRoles(string): the role of the domain user. Specify a tenant for the user.

Example:

{ "username": NetBrain, "email": [email protected], "firstName": NetBrain, "lastName": NetBrain, "password": ******, "authenticationType": null, "phoneNumber": null, "department": null, "description": null, "allowChangePassword": null, "deactivatedTime": null, "isSystemAdmin": null, "tenants": null }

Response




1.15.3. Delete users

Use this API to create user accounts in the system.




DELETE /V1/CMDB/Users Yes

Parameters

Name Description



username*required (path)

The name of the user that you want to delete.

Response




1.15.4. Get the usage report of users

Use this API to get the usage summary of a domain.



GET /V1/CMDB/Users/UsageReport Yes

Parameters

Name Description



tenantId (query)

Tenant ID.

domainId (query)

Domain ID.


Name Description

fromDate (query)

The start time. If not specified, use the initialization time when the system was installed. Format: <yyyy>-<mm>-<dd>T<hh>:<mm>:<ss>Z. For example, 2018-03-07T04:59:59Z.

toDate (query)

The end time. If not specified, use the current time. Format: <yyyy>-<mm>-<dd>T<hh>:<mm>:<ss>Z. For example, 2018-03-07T04:59:59Z.

Response


usageReport object The returned usage report. It contains the following parameters:

username: the name of a user.

ofLogins: the number of logins to the system.

lastLogoutTime: the time of the last logout of a user.

totalOnlineTime: the total online time of a user.

ofLoginFailureDueToSeatLicense: the number of login failures due to seat license.

{ "statusCode": 790200, "statusDescription": "success", "usageReport": [ { "username": "NetBrain", "ofLogins": "string", "firstTimeLogin": "string", "lastLogoutTime": "string", "totalOnlineTime": "string", "ofLoginFailureDueToSeatLicense": "string" } ] }



1.15.5. Get user information

Use this API to get the user information of a user.



Get /V1/CMDB/Users Yes

Parameters

Name Description




Name Description

username (query)

The name of the user that you get the information. If not specified, the API returns the information of all users.

Response


userData List The returned user information. It contains the following parameters:

username: the user name.

email: the email address of the user.

firstName: the first name of the user.

lastName: the last name of the user.

password: the login password.

authenticationType: the authentication type of the user account.

o 1: Local

o 2: External

phoneNumber: the phone number of the user.

department: the department that the user belongs to.

description: the description of the user account.

allowChangePassword: whether the user can change the password.

deactivatedTime: the time when the account is expired.

isSystemAdmin: whether the user is an administrator.

tenantsAndRoles: tenants that the user can access and the user roles.

o tenantId: the tenant that the user can access.

o isAdmin: decide whether to allocate the tenant administrator role to the user.

o canAddDomain: decide whether to allow the user to create domains.

{ "username": NetBrain, "email": [email protected], "firstName": NetBrain, "lastName": NetBrain, "password": ******, "authenticationType": null, "phoneNumber": null, "department": null, "description": null, "allowChangePassword": True, "deactivatedTime": null, "isSystemAdmin": True, "tenantsAndRoles": null }



1.16. API Status Code List

The system returns an API status code for each API call, which conveys the results of an API request.

The following table lists the status code for API calls.


Service Status Code HTTP Status Code Description

Success

790200 200 Success.

790201 201 Created (the result of POST method).

Parameter Validation Failure

791000 400 Null parameter.

791001 400 Invalid parameter.

791002 400 Invalid value.

791003 400 Parameter conflict.

791004 400 Invalid tenant.

791005 400 Invalid domain.

791006 400 Non-existing data.

791007 400 Data conflict.

791008 400 Unsupported feature.

791009 400 Null or invalid value.

792000 400 Attribute not editable.

792002 400 Attribute not supported.

792003 400 Built-in attribute deletion error.

792004 400 Field name violation.

792005 400 Value out of range.

792006 400 Alphabet string constraint.

792007 400 Character validation failed.

792008 400 Invalid address.

792009 400 Invalid type.

792010 400 The map is not existing.

792011 400 Unknown switch.

792030 400 Zero or negative value.

792031 400 Negative value.



792040 400 Unknown source gateway.

792100 400 Site transaction not found.

792102 400 Site locked.

792105 400 Trying to execute an operation that is invalid for a leaf site.

792110 400 Trying to execute an operation that is invalid for a container site.

Server Exception

793000 500 Unexpected Error.

793001 500 Inner exception.

793011 500 Task error.

Routing Error

793404 404 No routing resource found for given URL.

793405 405 The method is not supported for given HTTP request.

Task or Operation failure

794000 400 No IP to discover.

794001 409 The task is already in running state.

794002 400 Run disabled task.

794003 400 Task type is not scanned.

794004 400 The task is not existing.

794005 400 Failed to start a task.

794007 400 incomplete task.

794008 400 failed task.

794009 400 Canceled task.

794010 409 Operation conflict.

794011 400 Operation failed.

794100 400 Task type error, not a benchmark task.

794101 400 Task type error, not a discovery task.

Authentication Failure and Permission Error

795000 401 Authentication error.



795001 403 Insufficient permissions on tenant or domain.

795002 403 No permission to log into the system.

795003 403 Insufficient permissions.

795004 401 The session expired.

795005 401 Invalid token.

795006 408 Request timeout.

795007 402 Exceeds tenant available node.

795008 400 Do not allow resetting passwords.

795009 400 Do not allow modifying parameter.

795010 400 The session does not exist.

795011 402 API calls exceeded the limit.

795012 402 No API license or license expired (could be caused by license check failure).

External Approval for Change Management

798800 400 The change management failed to bind to a ticket.

798801 400 The change management was already bound to another ticket.

798802 400 The change management is not allowed to bind to a ticket.

798803 400 The change management state is not allowed to be changed.

798804 400 Failed to update the change management state.

798805 403 License missing or invalid.

1.17. Device Type Name and ID

The following table lists the predefined device types and the corresponding IDs.

Type Name ID

Cisco Router 2

Juniper Router 102

End System 1004


Type Name ID

Unclassified Device 1021

Cisco WAP 1025

Cisco IOS Switch 2001

Cisco PIX Firewall 2002

F5 Load Balancer 2003

Cisco Nexus Switch 2004

Checkpoint Firewall 2007

NetScreen Firewall 2008

Cisco ASA Firewall 2009

HP ProCurve Switch 2011

Juniper EX Switch 2012

Arista Switch 2013

Dell Force10 Switch 2015

Juniper SRX Firewall 2018

Unclassified Router 2021

Extreme Switch 2023

Brocade Switch 2024

Unclassified Firewall 2030

Unclassified Load Balancer 2035

HP Menu-Driven Switch 2041

Cisco Catalyst Switch 2060

Unclassified Switch 2061

Cisco CSS 2062

Nortel Switch 2110

Palo Alto Firewall 2130

Ciena Switch 2140

Enterasys Switch 2150

Cisco IOS XR 2999


Type Name ID

Call Manager 3001

IP Phone 3002

Cache Engine 3003

Cisco WLC 3033

LWAP 3034

Aruba WLC 3035

3Com Switch 3333

Planet WGSW 10002

Aerohive Wireless 10225

Dell Networking Switch 10327

MikroTik 10336

Xirrus Wireless Array 10339

Adtran 10352

Cisco ACE 10357

A10 Load Balancer 10369

Fortinet FortiGate Firewall 10380

Netscaler Load Balancer 10381

Sidewinder Firewall 10402

Hirschmann Switch 10416

Alcatel Lucent Service Router 10417

Alcatel OmniSwitch 10418

Radwin Radio Devices 10429

Huawei Switch 10430

Cisco UCS Fabric 10441

MRV 10455

RuggedCom ROX Switch 10457

Uplogix 10464


Type Name ID

SMC Switch 10465

Riverbed WAN Optimizer 10466

Tellabs Router 10485

RuggedCom RS(G) 10487

Avaya Switch 10513

Dell Sonicwall 10515

Casa 10516

Tellabs Switch 10524

Aruba LWAP 10529

Alcatel OmniStack Switch 10530

Dlink Switch 10531

Cisco WAAS 10532

Brocade Vyatta Router 10533

Juniper QFabric System 10540

SilverPeak WAN Optimizer 10541

Aruba IAP 10547

Cisco VDS 10563

Arris Router 10566

Calix E-Series 10567

Cisco Meraki AP 10571

Adva Optical 10586

Cisco Meraki Switch 10591

Avaya Router 10592

GigaVUE-OS 10611

Cisco Meraki Cloud 10613

Bluecoat 10615

Cisco Meraki Firewall 10616

Cisco MDS 10617


Type Name ID

Fujitsu Switch 10618

Viptela 10619

Redback Router 10623

Calix B-Series 10624

T-Marc 300 Series 10632

Avaya VSP 10659

IBM Switch 10660

Cisco Firepower Security Appliance 10669

Raisecom Switch 10800

Crossbeam Firewall 10811

Ubiquiti airMAX 10920

Moxa Switch 10921

Big Switch 10930

APC 10940

APC UPS 10941

Stonesoft NGFW 10945

Watchguard Firewall 10950

Oracle Acme 10951

Aruba Switch 11210

IBM DataPower 11232

Radware Alteon 11235

Cisco Firepower NGFW 12009

Digi Cellular Router 12220

Nexans GigaSwitch 12225

VM Host 13002

vSphere Standard Switch 13003

vSphere Distributed Switch 13004


Type Name ID

NSX Distributed Logical Router 21007

NSX Edge Security Gateway 21008

NSX Manager 21010

NSX Controller 21011

NSX Logical Switch 21012

Cisco ACI APIC 30001

Cisco ACI Spine Switch 30002

Cisco ACI Leaf Switch 30003

Fortinet Controller Managed Switch 30005

Fortinet Controller Managed AP 30008

1.18. Best Practices and Use Cases for NetBrain Rest APIs

This section introduces how to use NetBrain APIs to serve your network management via the following use cases:

Best Practices to Use NetBrain as CMDB via APIs

Manage Your NetBrain Data via APIs

Return Hop List of a Path in Third-party System


1.18.1. Best Practice to Use NetBrain as CMDB via APIs

NetBrain can be synchronized with data from external CMDBs while also providing Restful APIs for other NMS tools to read data from.

Two best practices will be introduced to describe how to use NetBrain as CMDB to maintain your network:

Using NetBrain Data to Populate Other CMDBs

Using Other CMDB Data to Populate NetBrain

1.18.1.1. Using NetBrain Data to Populate Other CMDBs

This best practice is recommended for users who use NetBrain as the primary CMDB and would like to populate

another vendor's database with NetBrain data.

Workflow

The pseudo-code below describes the main flow in the API script to export all device data from NetBrain database.

1. Login to NetBrain API server and get session 2. Set the current domain 3. Call GetAllDevices 4. For each device i. Call GetAllDeviceAttributes to get all device properties ii.Call GetAllInterfaces iii.For each interface a. Call GetAllInterfaceProperties to get all interface properties iv. Call GetAllModules iii.For each module


a. Call GetAllModuledProperties to get all module properties 5. Logout from Netbrain API server

API Script

You can refer to the script below to call relative APIs. This sample script first imports a python library maintained

by NetBrain and you need to write your own one in practical use.

import netbrain_restful_lib import time import urllib3 urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning) import pprint user = "NetBrain" pwd = "Netbrain" nb_url = "http(s)://<IP address of NetBrain Web Server>/" headers = {'Content-Type': 'application/json', 'Accept': 'application/json'} tenantName = "Initial Tenant" domainName = "Use Case" ################################################################# # Step 1: Login to NetBrain API server and get session print("Step 1") token = netbrain_restful_lib.loginSession(nb_url, user, pwd) print("Token: "+token) print(netbrain_restful_lib.getTenants(nb_url, token)) print(netbrain_restful_lib.getDomains(nb_url, token)) #Sample results # token : adf5b560-8e9c-4114-87bb-2eed24f0faff # tenantList : [{'tenantId': 'a50af282-fa02-012f-a7f7-e410cc7c29d3', 'tenantName': 'Initial Tenant'}] # domainList : [{'domainName': 'UseCase', 'domainId': '4f747a8b-71da-404b-a05c-e8505aa14725'}] tenantId = 'cb36f82b-4126-2fef-5310-c3a66f3dae4d' domainId = '6f9be63d-2290-4121-ae8b-c8fdb53a56ec' # Step 2: Set current domain print("Step 2") print(netbrain_restful_lib.loginDomain(nb_url, token, tenantId, domainId)) # Sample results # loginDomain: Login successfully! # Step 3: Call GetAllDevices #print("Step 3") #devices = netbrain_restful_lib.getDevice(nb_url, token, None) #print("Get All Devices: "+str(devices)) #devicelist = [] #for i in devices: # devicelist.append({"Device": i['hostname']})


# Sample results # Get All Devices : [{'id': 'ae18acc3-ee91-464d-b1d1-efd6cdecbcc9', 'mgmtIP': '172.16.8.199', 'hostname': 'NBCNBJ-SRX2', 'deviceTypeName': 'Juniper SRX Firewall'}, {'id': 'e1543c3a-d410-453d-b392-4f21e260d391', 'mgmtIP': '172.16.8.199'}] devicelist = [{'Device': 'NBCNBJ-SRX2'}] # Step 4(i): For each device, call GetAllDeviceAttributes to get all device properties print("Step 4(i)") for i in devicelist: deviceattributes = netbrain_restful_lib.getDeviceAttributes(nb_url, token, i['Device'], None) print("Device attributes of "+i['Device']+ " are "+ str(deviceattributes)) # Sample results # Device attributes of NBCNBJ-SRX2 are {'name': 'NBCNBJ-SRX2', 'mgmtIP': '172.16.8.199', 'mgmtIntf': 'ge-7/0/8.0', 'subTypeName': 'Juniper SRX Firewall', 'vendor': 'Juniper', 'model': 'SRX', 'ver': '12.1X46-D20.5', 'sn': '212787163ef9', 'site': 'My Network\\Asia\\China\\BJ', 'loc': '', 'contact': '', 'mem': '', 'assetTag': '', 'layer': '', 'descr': '', 'oid': '1.3.6.1.4.1.2636.1.1.1.2.96', 'driverName': 'Juniper SRX Firewall', 'assignTags': '', 'hasBGPConfig': False, 'hasOSPFConfig': True, 'hasEIGRPConfig': False, 'has ISISConfig': False, 'hasMulticastConfig': False, 'attributeName': ''} i['Device Attributes'] = deviceattributes # Step 4(ii): For each device, call GetAllInterfaces print("Step 4(ii)") for i in devicelist: interfaces = netbrain_restful_lib.getInterfaces(nb_url, token, i['Device']) print("Interfaces of "+i['Device']+ " are "+ str(interfaces)) # Sample results # Interfaces of NBCNBJ-SRX2 are ['ge-0/0/2.0', 'ge-0/0/3.0', 'ge-0/0/4.0'] interfacelist = [] for j in interfaces: interfacelist.append({"Interface Name":j}) # Step 4(iii): For each interface, call GetAllInterfaceProperties to get all interface properties print("Step 4(iii)") for k in interfacelist: interfaceAttributes = netbrain_restful_lib.getInterfaceAttributes(nb_url, token, i['Device'], k["Interface Name"], None) print("Interface atributes are: "+str(interfaceAttributes)) # Sample results # Interface atributes are: Interface Attributes :{'hostname': 'NBUSCA-SW7', 'attributes': {'Vlan1': {'name': 'Vlan1', 'ips': '', 'ipv6s': '', 'ipv6LinkLocalAddress': '', 'mibIndex': 10, 'bandwidth': 1000000, 'speed': '', 'duplex': '', 'intfStatus': 'administratively down/down', 'macAddr': 'aabb.cc81.6100', 'moduleSlot': '', 'moduleType': '', 'descr': '', 'routingProtocol': '', 'multicastMode': '', 'mplsVrf': '', 'inAclName': '', 'outAclName': '', 'mode': '', 'vlan': '', 'trunkNativeVlan': '', 'trunkEncapsulation': '', 'ipUnnumberedIp': ''}}, 'statusCode': 790200, 'statusDescription': 'Success.'} k['Interface Attributes'] = interfaceAttributes i['Interfaces'] = interfacelist


pprint.pprint(devicelist) # Step 10: Logout to NetBrain API server print("Step 10") print(netbrain_restful_lib.logoutSession(nb_url, token))

1.18.1.2. Using Other CMDB Data to Populate NetBrain

This best practice is recommended for users who maintain another vendor as the primary CMDB and would like to

populate NetBrain database with information from the CMDB.

Workflow

The pseudo-code below describes the main flow in the API script to import data from the CMDB to NetBrain.

1. Login to NetBrain API server and get session 2. Set the current domain 3. Create custom device attribute using CreateDeviceAttribute 4. Create custom interface attribute using CreateInterfaceAttribute 5. For every device a. Set value of the custom device attribute b. For every interface 1. Set value of the custom interface attribute 6. Logout Netbrain API server

API Script



import netbrain_restful_lib import time import urllib3 urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning) import pprint user = "NetBrain" pwd = "NetBrain" nb_url = "http(s)://<IP address of NetBrain Web Server>/" headers = {'Content-Type': 'application/json', 'Accept': 'application/json'} tenantName = "Initial Tenant" domainName = "Use Case" #################################################################


# Step 1: Login to NetBrain API server and get session print("Step 1") token = netbrain_restful_lib.loginSession(nb_url, user, pwd) print("Token: "+token) print(netbrain_restful_lib.getTenants(nb_url, token)) print(netbrain_restful_lib.getDomains(nb_url, token)) #Sample results # token : adf5b560-8e9c-4114-87bb-2eed24f0faff # tenantList : [{'tenantId': 'a50af282-fa02-012f-a7f7-e410cc7c29d3', 'tenantName': 'Initial Tenant'}] # domainList : [{'domainName': 'UseCase', 'domainId': '4f747a8b-71da-404b-a05c-e8505aa14725'}] tenantId = 'cb36f82b-4126-2fef-5310-c3a66f3dae4d' domainId = '6f9be63d-2290-4121-ae8b-c8fdb53a56ec' # Step 2: Set current domain print("Step 2") print(netbrain_restful_lib.loginDomain(nb_url, token, tenantId, domainId)) # Sample results # loginDomain: Login successfully! # The data which needs to be imported data=[{"device":"NBUSMA-R1", "DeviceAtt1":"Value of DeviceAtt1", "interfaces":[{'interface': "f3/0 10.30.7.147/29", "InterfaceAtt1":"Value of InterfaceAtt1"},{'interface': "f0/0 172.16.8.192/22", "InterfaceAtt1":"Value of InterfaceAtt1"}] }] # Step3: Create custom device attribute using CreateDeviceAttribute print("Step 3") attributeName= "DeviceAtt1" attributeDisplayName="DeviceAtt1" deviceTypeNames="Null" dataType="string" isFullSearch=True print(netbrain_restful_lib.createDeviceAttribute(nb_url, token, attributeName, attributeDisplayName, deviceTypeNames, dataType, isFullSearch)) # Step4: Create custom interface attribute using CreateInterfaceAttribute print("Step 4") interfaceType="intfs" attributeName= "InterfaceAtt1" attributeDisplayName="InterfaceAtt1" deviceTypeNames="Null" dataType="string" isFullSearch=True print(netbrain_restful_lib.createInterfaceAttribute(nb_url, token, interfaceType, attributeName, attributeDisplayName, deviceTypeNames, dataType, isFullSearch)) # Step 5a: For every device, set value of the custom device attribute


print("Step 5a") for i in data: print(i["device"]) print(i["DeviceAtt1"]) print(netbrain_restful_lib.setDeviceAttribute(nb_url, token, i["device"], "DeviceAtt1", i["DeviceAtt1"])) # Step 5b: For every interface, set value of the custom interface attribute print("Step 5b") for j in i["interfaces"]: #print(j["interface"]) #print(j["InterfaceAtt1"]) print(netbrain_restful_lib.setInterfaceAttribute(nb_url, token, i["device"], "InterfaceAtt1", j["InterfaceAtt1"], j["interface"])) # Step 6: Logout to NetBrain API server print("Step 6") print(netbrain_restful_lib.logoutSession(nb_url, token))

1.18.2. Use Case - Manage Your NetBrain Data via APIs

When you live network changes, the data in NetBrain will be out of data. NetBrain provides APIs to allow you to

manage these changes.

The following use cases will be introduced to describe how to manage data changes via APIs:

Triggering NetBrain to Discover or Remove devices

Re-discovering Hostname-Changed Devices

1.18.2.1. Triggering NetBrain to Discover or Remove Devices

An enterprise usually deploys a configuration management database (CMDB) tool (such as HP NA) to maintain an

accurate repository of network devices. NetBrain supports to integrate with these CMDB tools to ensure the data accuracy in NetBrain domains. That is, whenever new devices are added into or removed from a CMDB, the CMDB can trigger NetBrain to either discover or remove the devices.

Discovering Devices via APIs

Removing Devices via APIs

Discovering Devices via APIs

This section covers the use case to discover new devices via APIs.


Workflow

The pseudo-code below describes the main flow in the API script to discover devices to NetBrain.

1. Login to NetBrain API server and get session 2. Set the current domain 3. Call GetAllDiscoveryTasks and pick up one task 4. For each newly added device i. Call AddIPforDiscovery to add its IP and/or credentials into the task 5. Call GetAllIPsForDiscovery and confirm that all IPs are added successfully 6. Call RunDiscoveryNow to run the discovery task 7. Keep calling GetDiscoveryTaskStatus each one minute till the task is completed or completed with error 8. Call GetDiscoveryTaskResult to get all IPs the task has tried to discover 9. For each IP in results i. If (ping failed) print “ping failed” ii. If (Telnet/SSH status failed) a. Call GetLiveAccessLog and print out the live access log 10. Logout to NetBrain API server

API Script



import netbrain_restful_lib import time user = "NetBrain" pwd = "Netbrain" nb_url = "http(s)://<IP address of NetBrain Web Server>/" headers = {'Content-Type': 'application/json', 'Accept': 'application/json'} tenantName = "Initial Tenant" domainName = "Use Case" ################################################################# # Step 1: Login to NetBrain API server and get session token = netbrain_restful_lib.loginSession(nb_url, user, pwd) tenantList = netbrain_restful_lib.getTenants(nb_url, token) domainList = netbrain_restful_lib.getDomains(nb_url, token) #Sample results # token : adf5b560-8e9c-4114-87bb-2eed24f0faff # tenantList : [{'tenantId': 'a50af282-fa02-012f-a7f7-e410cc7c29d3', 'tenantName': 'Initial Tenant'}] # domainList : [{'domainName': 'UseCase', 'domainId': '4f747a8b-71da-404b-a05c-e8505aa14725'}] tenantId = 'fcf8a380-6b11-0fed-1d51-3b4cdef8f238' domainId = '25b66365-1ab8-4fed-90c9-1307a4047c3d' # Step 2: Set current domain print(netbrain_restful_lib.loginDomain(nb_url, token, tenantId, domainId)) # Sample results


# loginDomain: Login successfully! # Step 3: Call GetAllDiscoveryTasks and pick up one task print(netbrain_restful_lib.getDiscoveryTasks(nb_url, token)) taskId = "1696faa7-749c-78a7-eaad-fcf815b11e4a" # Sample results # GetAllDiscoveryTasks : [{"id": "1696faa7-749c-78a7-eaad-fcf815b11e4a", "name": "Scheduled System Discovery", "enable": true, "lastStatus": "", "lastRunSpan": "00:00:00", "curStatus": "Not Started", "nextRunTime": "1/2/3000,12:00:00 AM", "frequency": "Once"}] # Step 4: For each newly added device, call AddIPforDiscovery to add its IP and/or credentials into the task data=[{"IP":"192.168.0.1", "cliType":0} ] for i in data: print(netbrain_restful_lib.postIPstoDiscoveryTask(nb_url, token, taskId, i['IP'], i["cliType"])) # Sample results # postIPstoDiscoveryTask : Success # Step 5: Call GetAllIPsForDiscovery and confirm that all IPs are added successfully print(netbrain_restful_lib.getIPinDiscoveryTask(nb_url, token, taskId)) # Sample results # getIPinDiscoveryTask: ["192.168.0.1"] # Step 6: Call RunDiscoveryNow to run the discovery task print(netbrain_restful_lib.runDiscoveryTask(nb_url, token, taskId)) # Sample results # runDiscoveryTask: Success # Step 7: Keep calling GetDiscoveryTaskStatus each one minute till the task is completed or completed with error print(netbrain_restful_lib.getDiscoveryRunningStatus(nb_url, token, taskId)) # Sample results # getDiscoveryRunningStatus: 10 #Possible values-1 Unknown, 0 Never run, 2 Running, 10 Succeeded, 11 Succeeded with warning, 20 Failed, 30 Manually stopped, 31 Automatically stopped due to timeout set by user or other system setting # Step 8: Call GetDiscoveryTaskResult to get all IPs the task has tried to discover print(netbrain_restful_lib.getDiscoveryResults(nb_url, token, taskId)) # Sample results # getDiscoveryResults: [{"domainId": "Domain","source": "Scan 172.24.101.12/32","hostname": "Bos-Core1", "frontServer": "10.10.1.43", "ping": "Succeeded", "SNMP": "nb", "vendor": "Cisco", "oid": "1.3.6.1.4.1.9.1.324","type": "Cisco IOS Switch", "config": "Succeeded", "telnetSSH": "Succeeded" } ] # Step 9: For each IP in results, check if results failed. If (Telnet/SSH status failed), call GetLiveAccessLog and print out the live access log


print(netbrain_restful_lib.getDiscoveryLiveAccessLog(nb_url, token, taskId)) # Sample results # getDiscoveryLiveAccessLog: [{"mgmtIP": "172.24.101.12", "liveLogs": "Ping [172.24.101.12] via Proxy Server(10.10.1.43); Succeeded\r\nSend RO = [nb][version:v2c] to [172.24.101.12] via Proxy Server(10.10.1.43); Succeeded\r\nRetrieving [172.24.101.12]'s Hostname ,Vendor and Model via Proxy Server(10.10.1.43); Succeeded\r\nTelnet to device 172.24.101.12 via Proxy Server(10.10.1.43)\nTelnet to device 172.24.101.12 successfully via Proxy Server(10.10.1.43)\nReturn from Device:[ Username:]\nSending Username:nb\nReturn from Device:[Password:]\nSending Password:******\nReturn from Device:[BJ_Dis_SW2>]\nSending \"enable\" command\nReturn from Device:[Password:]\nSending Enable Password:******\nReturn from Device:[BJ_Dis_SW2#]\nSending \"enable\" command\nReturn from Device:[BJ_Dis_SW2#]\nSending \"terminal length 0\" command\nReturn from Device:[BJ_Dis_SW2#]\nSending \"show run\" command\nReceived:BJ_Dis_SW2#show run\r\nBuilding configuration...\r\n\r\r\n\r\nSending \"exit\" command\nTelnet to device 172.24.101.12 disconnected.\nUpdate configuration file of BJ_Dis_SW2 successfully,(0.546s)\r\nDiscovery of 172.24.101.12 complete"}] # Step 10: Logout to NetBrain API server print(netbrain_restful_lib.logoutSession(nb_url, token))

Removing Devices via APIs

This section covers the use case to remove devices from NetBrain domain via APIs.

Workflow

The pseudo-code below describes the main flow in the API script to remove devices.

1. Login to NetBrain API server and get session 2. Set the current domain 3. Delete device from domain 4. Confirm that device is no longer in workspace 5. Logout to NetBrain API server

API Script



import netbrain_restful_lib import time import urllib3 urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning) user = "Demo" pwd = "Netbrain1" nb_url = "http(s)://<IP address of NetBrain Web Server>/" headers = {'Content-Type': 'application/json', 'Accept': 'application/json'} tenantName = "Initial Tenant" domainName = "Use Case" #################################################################


# Step 1: Login to NetBrain API server and get session print("Step 1") token = netbrain_restful_lib.loginSession(nb_url, user, pwd) print("Token: "+token) print(netbrain_restful_lib.getTenants(nb_url, token)) print(netbrain_restful_lib.getDomains(nb_url, token)) #Sample results # token : adf5b560-8e9c-4114-87bb-2eed24f0faff # tenantList : [{'tenantId': 'a50af282-fa02-012f-a7f7-e410cc7c29d3', 'tenantName': 'Initial Tenant'}] # domainList : [{'domainName': 'UseCase', 'domainId': '4f747a8b-71da-404b-a05c-e8505aa14725'}] tenantId = 'df20d549-d8ae-52ee-b842-036158d1083d' domainId = '9df0d29e-7792-482d-a590-0620f4e8788f' # Step 2: Set current domain print("Step 2") print(netbrain_restful_lib.loginDomain(nb_url, token, tenantId, domainId)) # Sample results # loginDomain: Login successfully! # Step 3. Delete device from domain print("Step 3") deviceName="NBUSMA-SW1" print(netbrain_restful_lib.deleteDevice(nb_url, token, deviceName)) # Sample results # Delete Device: Success # Step 4. Confirm that device is no longer in workspace print("Step 4") deviceName="NBUSMA-SW1" print(netbrain_restful_lib.getDevice(nb_url, token, deviceName)) # Sample result should show NULL device list # Get Devices: [] # Step 5: Logout to NetBrain API server print("Step 5") print(netbrain_restful_lib.logoutSession(nb_url, token))

1.18.2.2. Re-discovering Hostname-Changed Devices

When the hostname of a device in your live network changes, this device need to be removed and then re-

discovered to NetBrain. You can utilize NetBrain APIs to execute the domain management tasks of this kind.


Workflow

The pseudo-code below describes the main flow in the API script to execute the change.

1. Login to NetBrain API server and get session 2. Set the current domain 3. Remove device from workspace 4. Confirm the device is removed from workspace 5. Call GetAllDiscoveryTasks and pick up one task 6. Call AddIPforDiscovery to add its IP and/or credentials into the task 7. Call GetAllIPsForDiscovery and confirm that all IPs are added successfully 8. Call RunDiscoveryNow to run the discovery task 9. Keep calling GetDiscoveryTaskStatus each one minute till the task is completed or completed with error 10. Call GetDiscoveryTaskResult to get all IPs the task has tried to discover 11. For each IP in results i. If (ping failed) print “ping failed” ii. If (Telnet/SSH status failed) a. Call GetLiveAccessLog and print out the live access log 12. Logout to NetBrain API server

API Script



You can refer to the script below to call relative APIs. This sample script first imports a python library maintained by NetBrain and you need to write your own one in practical use. import netbrain_restful_lib import time import urllib3 urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning) user = "NetBrain" pwd = "Netbrain" nb_url = "http(s)://<IP address of NetBrain Web Server>/" headers = {'Content-Type': 'application/json', 'Accept': 'application/json'} tenantName = "Initial Tenant" domainName = "Use Case" ################################################################# # Step 1: Login to NetBrain API server and get session print("Step 1") token = netbrain_restful_lib.loginSession(nb_url, user, pwd) print("Token: "+token) print(netbrain_restful_lib.getTenants(nb_url, token)) print(netbrain_restful_lib.getDomains(nb_url, token)) #Sample results # token : adf5b560-8e9c-4114-87bb-2eed24f0faff # tenantList : [{'tenantId': 'a50af282-fa02-012f-a7f7-e410cc7c29d3', 'tenantName': 'Initial


Tenant'}] # domainList : [{'domainName': 'UseCase', 'domainId': '4f747a8b-71da-404b-a05c-e8505aa14725'}] tenantId = 'df20d549-d8ae-52ee-b842-036158d1083d' domainId = '9df0d29e-7792-482d-a590-0620f4e8788f' # Step 2: Set current domain print("Step 2") print(netbrain_restful_lib.loginDomain(nb_url, token, tenantId, domainId)) # Sample results # loginDomain: Login successfully! # Step 3. Delete device from domain print("Step 3") deviceName="NBUSMA-SW1" print(netbrain_restful_lib.deleteDevice(nb_url, token, deviceName)) # Sample results # Delete Device: Success # Step 4. Confirm that device is no longer in workspace print("Step 4") deviceName="NBUSMA-SW1" print(netbrain_restful_lib.getDevice(nb_url, token, deviceName)) # Sample result should show NULL device list # Get Devices: [] # Step 5: Call GetAllDiscoveryTasks and pick up one task print("Step 5") print(netbrain_restful_lib.getDiscoveryTasks(nb_url, token)) # Sample results # GetAllDiscoveryTasks : [{"id": "1696faa7-749c-78a7-eaad-fcf815b11e4a", "name": "Scheduled System Discovery", "enable": true, "lastStatus": "", "lastRunSpan": "00:00:00", "curStatus": "Not Started", "nextRunTime": "1/2/3000,12:00:00 AM", "frequency": "Once"}] taskId = "e86e73da-1829-fd8e-4f83-98f524533779" # Step 6: For each newly added device, call AddIPforDiscovery to add its IP and/or credentials into the task print("Step 6") data=[{"IP":"1.1.1.1", "cliType":0} ] for i in data: print(netbrain_restful_lib.postIPstoDiscoveryTask(nb_url, token, taskId, i['IP'], i["cliType"])) # Sample results # postIPstoDiscoveryTask : Success # Step 7: Call GetAllIPsForDiscovery and confirm that all IPs are added successfully print("Step 7")


print(netbrain_restful_lib.getIPinDiscoveryTask(nb_url, token, taskId)) # Sample results # getIPinDiscoveryTask: ["192.168.0.1"] # Step 8: Call RunDiscoveryNow to run the discovery task print("Step 8") print(netbrain_restful_lib.runDiscoveryTask(nb_url, token, taskId)) time.sleep(2) # Sample results # runDiscoveryTask: Success # Step 9: Keep calling GetDiscoveryTaskStatus each one minute till the task is completed or completed with error print("Step 9") status = netbrain_restful_lib.getDiscoveryRunningStatus(nb_url, token, taskId) print("getDiscoveryRunningStatus: "+status) while ("2" in netbrain_restful_lib.getDiscoveryRunningStatus(nb_url, token, taskId)): print("Discovery Task still running") time.sleep(15) # Sample results # getDiscoveryRunningStatus: 10 #Possible values-1 Unknown, 0 Never run, 2 Running, 10 Succeeded, 11 Succeeded with warning, 20 Failed, 30 Manually stopped, 31 Automatically stopped due to timeout set by user or other system setting # Step 9: Call GetDiscoveryTaskResult to get all IPs the task has tried to discover print("Step 9") print(netbrain_restful_lib.getDiscoveryResults(nb_url, token, taskId)) # Sample results # getDiscoveryResults: [{"domainId": "Domain","source": "Scan 172.24.101.12/32","hostname": "Bos-Core1", "frontServer": "10.10.1.43", "ping": "Succeeded", "SNMP": "nb", "vendor": "Cisco", "oid": "1.3.6.1.4.1.9.1.324","type": "Cisco IOS Switch", "config": "Succeeded", "telnetSSH": "Succeeded" } ] # Step 10: For each IP in results, check if results failed. If (Telnet/SSH status failed), call GetLiveAccessLog and print out the live access log print("Step 10") print(netbrain_restful_lib.getDiscoveryLiveAccessLog(nb_url, token, taskId)) # Sample results # getDiscoveryLiveAccessLog: [{"mgmtIP": "172.24.101.12", "liveLogs": "Ping [172.24.101.12] via Proxy Server(10.10.1.43); Succeeded\r\nSend RO = [nb][version:v2c] to [172.24.101.12] via Proxy Server(10.10.1.43); Succeeded\r\nRetrieving [172.24.101.12]'s Hostname ,Vendor and Model via Proxy Server(10.10.1.43); Succeeded\r\nTelnet to device 172.24.101.12 via Proxy Server(10.10.1.43)\nTelnet to device 172.24.101.12 successfully via Proxy Server(10.10.1.43)\nReturn from Device:[ Username:]\nSending Username:nb\nReturn from Device:[Password:]\nSending Password:******\nReturn from Device:[BJ_Dis_SW2>]\nSending \"enable\" command\nReturn from Device:[Password:]\nSending Enable Password:******\nReturn from Device:[BJ_Dis_SW2#]\nSending \"enable\" command\nReturn from Device:[BJ_Dis_SW2#]\nSending \"terminal length 0\" command\nReturn from Device:[BJ_Dis_SW2#]\nSending \"show run\" command\nReceived:BJ_Dis_SW2#show run\r\nBuilding configuration...\r\n\r\r\n\r\nSending \"exit\"


command\nTelnet to device 172.24.101.12 disconnected.\nUpdate configuration file of BJ_Dis_SW2 successfully,(0.546s)\r\nDiscovery of 172.24.101.12 complete"}] # Step 12: Logout to NetBrain API server print("Step 12") print(netbrain_restful_lib.logoutSession(nb_url, token))

1.18.2.3. Synchronizing Site Structure to NetBrain from Third-party System

If you maintain the site structure of your network in a third-party system, you can build the site structure and fully synchronize the sites to NetBrain from the third-party system via NetBrain APIs. Generally, the synchronization

takes two steps:

1. Create all sites.

2. Assign all devices into the sites.

Workflow

The pseudo-code below describes the main flow in the API script to synchronize the sites.

1. Login to NetBrain API server and get session 2. Set current domain 3. Create a list of full site names for all sites 4. Call CreateSites 5. For each leaf address i. Get a list of the hostnames of all devices assigned to this leaf site ii. Call SetDevicesOfSite to set devices of the leaf site 6. Call Commit to commit the change 7. Call GetSiteTree to confirm that all sites are created and devices are set 8. Logout NetBrain API server

API Script



import netbrain_restful_lib import time user = "NetBrain" pwd = "Netbrain" nb_url = "http(s)://<IP address of NetBrain Web Server>/" headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}


tenantName = "Initial Tenant" domainName = "Use Case" ################################################################# # Step 1: Login to NetBrain API server and get session token = netbrain_restful_lib.loginSession(nb_url, user, pwd) tenantList = netbrain_restful_lib.getTenants(nb_url, token) domainList = netbrain_restful_lib.getDomains(nb_url, token) #Sample results # token : adf5b560-8e9c-4114-87bb-2eed24f0faff # tenantList : [{'tenantId': 'a50af282-fa02-012f-a7f7-e410cc7c29d3', 'tenantName': 'Initial Tenant'}] # domainList : [{'domainName': 'UseCase', 'domainId': '4f747a8b-71da-404b-a05c-e8505aa14725'}] tenantId = 'fcf8a380-6b11-0fed-1d51-3b4cdef8f238' domainId = '25b66365-1ab8-4fed-90c9-1307a4047c3d' # Step 2: Set current domain print(netbrain_restful_lib.loginDomain(nb_url, token, tenantId, domainId)) # Sample results # loginDomain: Login successfully! # Step 3: Create a list of full site names for all sites. In this "full synchronization" use case we are listing all leaf containers and their corresponding devices data=[{"sitePath":"My Network/US/MA/Boston", "devices":["NBUSCA-ASA1XAact"]} ] # Step 4: Call CreateSites to create all leaf containers print(netbrain_restful_lib.createSiteTransaction(nb_url, token)) sites=[] for i in data: sites.append({"sitePath":i['sitePath'], "isContainer":False}) print(sites) print(netbrain_restful_lib.createSites(nb_url, token, sites)) print(netbrain_restful_lib.commitSiteTransaction(nb_url, token)) #Call Commit to commit the change # Sample results # CreateSiteTransaction: Site transaction created! # CreateSites: Site Created successfully! [{'sitePath': 'My Network/NA/US/TX', 'isContainer': True}] # CommitSiteTransaction: Site commit True # Step 5: For each leaf address, get a list of the hostnames of all devices assigned to this leaf site. Call SetDevicesOfSite to set devices of the leaf site netbrain_restful_lib.keepAliveSiteTransaction(nb_url, token) for i in data: print(i['sitePath']) print(i["devices"]) print(netbrain_restful_lib.addSiteDevice(nb_url, token, None, i['sitePath'], i["devices"])) # Sample results # AddSiteDevice: Devices added successfully!


# Step 6: Call Commit to commit the change print(netbrain_restful_lib.commitSiteTransaction(nb_url, token)) # Sample results # CommitSiteTransaction: Site commit True # Step 7: Call GetSiteTree to confirm that all sites are created and devices are set print(netbrain_restful_lib.getChildSites(nb_url, token, None, "My Network")) for i in data: print(netbrain_restful_lib.getSiteInfo(nb_url, token, None, i['sitePath'])) print(netbrain_restful_lib.getSiteDevice(nb_url, token, None, i['sitePath'])) # Sample results # GetChildSites: [{'siteId': 'aac212cb-fa84-4ddd-8c0b-18a00ec9c323', 'isContainer': False, 'siteType': 2, 'sitePath': 'My Network/NA/US/MA'}, {'siteId': '3ebb978f-323a-4308-8b38-82fa1a0a135f', 'isContainer': False, 'siteType': 2, 'sitePath': 'My Network/NA/US/CA'}] # GetSiteInfo: {'isContainer': True, 'siteId': 'ede2ed2b-d5cf-48dd-b341-020330757033', 'sitePath': 'My Network/NA/US', 'siteType': 1} # GetSiteDevice: [{'mgmtIP': '172.16.8.186', 'id': '06840b62-8a67-4cb2-9ed4-e540ea36fdcf', 'hostname': 'NBUSMA-SW7'}, {'mgmtIP': '172.16.8.194', 'id': '0b152c13-34e0-474e-aa4c-b07fe71cc0b7', 'hostname': 'NBUSMA-R1'}] # Step 8: Logout Netbrain API server netbrain_restful_lib.logoutSession(nb_url, token)

1.18.2.4. Synchronizing Site Updates from Third-party System

If you maintain and update site structures in another vendor, you can use NetBrain APIs to make the same site

updates in NetBrain, such as adding sites and removing devices from a site.

Use Case 1: Replace Devices in a Site

Workflow

The pseudo-code below describes the main flow in the API script to replace devices in a site.

1. Login to NetBrain API server and get session 2. Set current domain 3. Replace devices to existing site 4. Call Commit to commit the change 5. Call GetSiteTree to confirm that all sites are created and devices are set 6. Logout NetBrain API server

API Script




import netbrain_restful_lib import time import urllib3 urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning) user = "NetBrain" pwd = "Netbrain" nb_url = "http(s)://<IP address of NetBrain Web Server>/" headers = {'Content-Type': 'application/json', 'Accept': 'application/json'} tenantName = "Initial Tenant" domainName = "Use Case" ################################################################# # Step 1: Login to NetBrain API server and get session print("Step 1") token = netbrain_restful_lib.loginSession(nb_url, user, pwd) print("Token: "+token) print(netbrain_restful_lib.getTenants(nb_url, token)) print(netbrain_restful_lib.getDomains(nb_url, token)) #Sample results # token : adf5b560-8e9c-4114-87bb-2eed24f0faff # tenantList : [{'tenantId': 'a50af282-fa02-012f-a7f7-e410cc7c29d3', 'tenantName': 'Initial Tenant'}] # domainList : [{'domainName': 'UseCase', 'domainId': '4f747a8b-71da-404b-a05c-e8505aa14725'}] tenantId = 'fcf8a380-6b11-0fed-1d51-3b4cdef8f238' domainId = '25b66365-1ab8-4fed-90c9-1307a4047c3d' # Step 2: Set current domain print("Step 2") print(netbrain_restful_lib.loginDomain(nb_url, token, tenantId, domainId)) # Sample results # loginDomain: Login successfully! # Step 3: Replace devices to existing site print("Step 3") data=[{"sitePath":"My Network/US/CA/San Diego", "devices":["BSTX"]} ] print(netbrain_restful_lib.createSiteTransaction(nb_url, token)) for i in data: print(i['sitePath']) print(i["devices"]) print(netbrain_restful_lib.replaceSiteDevice(nb_url, token, None, i['sitePath'], i["devices"])) # Sample results # CreateSiteTransaction: Site transaction created! # ReplaceSiteDevice: Device moved successfully! # Step 4: Call Commit to commit the change print("Step 4") print(netbrain_restful_lib.commitSiteTransaction(nb_url, token))


# Sample results # CommitSiteTransaction: Site commit True # Step 5: Call GetSiteTree to confirm that all sites are created and devices are set print("Step 5") print(netbrain_restful_lib.getChildSites(nb_url, token, None, "My Network")) for i in data: print(netbrain_restful_lib.getSiteInfo(nb_url, token, None, i['sitePath'])) print(netbrain_restful_lib.getSiteDevice(nb_url, token, None, i['sitePath'])) # Sample results # GetChildSites: [{'siteId': 'aac212cb-fa84-4ddd-8c0b-18a00ec9c323', 'isContainer': False, 'siteType': 2, 'sitePath': 'My Network/NA/US/MA'}, {'siteId': '3ebb978f-323a-4308-8b38-82fa1a0a135f', 'isContainer': False, 'siteType': 2, 'sitePath': 'My Network/NA/US/CA'}] # GetSiteInfo: {'isContainer': True, 'siteId': 'ede2ed2b-d5cf-48dd-b341-020330757033', 'sitePath': 'My Network/NA/US', 'siteType': 1} # GetSiteDevice: [{'mgmtIP': '172.16.8.186', 'id': '06840b62-8a67-4cb2-9ed4-e540ea36fdcf', 'hostname': 'NBUSMA-SW7'}, {'mgmtIP': '172.16.8.194', 'id': '0b152c13-34e0-474e-aa4c-b07fe71cc0b7', 'hostname': 'NBUSMA-R1'}] # Step 6: Logout Netbrain API server print("Step 6") print(netbrain_restful_lib.logoutSession(nb_url, token))

Use Case 2: Remove Devices from a Site

Workflow

The pseudo-code below describes the main flow in the API script to remove devices from a site.

1. Login to NetBrain API server and get session 2. Set current domain 3. Remove device from leaf site 4. Call Commit to commit the change 5. Call GetSiteTree to confirm that all sites are created and devices are set 6. Logout NetBrain API server

API Script



import netbrain_restful_lib import time import urllib3 urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning) user = "NetBrain" pwd = "Netbrain" nb_url = "http(s)://<IP address of NetBrain Web Server>/" headers = {'Content-Type': 'application/json', 'Accept': 'application/json'} tenantName = "Initial Tenant" domainName = "Use Case"


################################################################# # Step 1: Login to NetBrain API server and get session print("Step 1") token = netbrain_restful_lib.loginSession(nb_url, user, pwd) print("Token: "+token) print(netbrain_restful_lib.getTenants(nb_url, token)) print(netbrain_restful_lib.getDomains(nb_url, token)) #Sample results # token : adf5b560-8e9c-4114-87bb-2eed24f0faff # tenantList : [{'tenantId': 'a50af282-fa02-012f-a7f7-e410cc7c29d3', 'tenantName': 'Initial Tenant'}] # domainList : [{'domainName': 'UseCase', 'domainId': '4f747a8b-71da-404b-a05c-e8505aa14725'}] tenantId = 'fcf8a380-6b11-0fed-1d51-3b4cdef8f238' domainId = '25b66365-1ab8-4fed-90c9-1307a4047c3d' # Step 2: Set current domain print("Step 2") print(netbrain_restful_lib.loginDomain(nb_url, token, tenantId, domainId)) # Sample results # loginDomain: Login successfully! # Step 3: Remove device from leaf site print("Step 3") data=[{"sitePath":"My Network/US/CA/San Diego", "devices":["BSTX"]} ] print(netbrain_restful_lib.createSiteTransaction(nb_url, token)) for i in data: print(i['sitePath']) print(i["devices"]) print(netbrain_restful_lib.deleteSiteDevice(nb_url, token, None, i['sitePath'], i["devices"])) # Sample results # CreateSiteTransaction: Site transaction created! # DeleteSiteDevice: Device removed successfully! # Step 4: Call Commit to commit the change print("Step 4") print(netbrain_restful_lib.commitSiteTransaction(nb_url, token)) # Sample results # CommitSiteTransaction: Site commit True # Step 5: Call GetSiteTree to confirm that all sites are created and devices are set print("Step 5") print(netbrain_restful_lib.getChildSites(nb_url, token, None, "My Network")) for i in data: print(netbrain_restful_lib.getSiteInfo(nb_url, token, None, i['sitePath'])) print(netbrain_restful_lib.getSiteDevice(nb_url, token, None, i['sitePath'])) # Sample results # GetChildSites: [{'siteId': 'aac212cb-fa84-4ddd-8c0b-18a00ec9c323', 'isContainer': False,


'siteType': 2, 'sitePath': 'My Network/NA/US/MA'}, {'siteId': '3ebb978f-323a-4308-8b38-82fa1a0a135f', 'isContainer': False, 'siteType': 2, 'sitePath': 'My Network/NA/US/CA'}] # GetSiteInfo: {'isContainer': True, 'siteId': 'ede2ed2b-d5cf-48dd-b341-020330757033', 'sitePath': 'My Network/NA/US', 'siteType': 1} # GetSiteDevice: [{'mgmtIP': '172.16.8.186', 'id': '06840b62-8a67-4cb2-9ed4-e540ea36fdcf', 'hostname': 'NBUSMA-SW7'}, {'mgmtIP': '172.16.8.194', 'id': '0b152c13-34e0-474e-aa4c-b07fe71cc0b7', 'hostname': 'NBUSMA-R1'}] # Step 6: Logout Netbrain API server print("Step 6") print(netbrain_restful_lib.logoutSession(nb_url, token))

Use Case 3: Delete a Site

Workflow

The pseudo-code below describes the main flow in the API script to delete a site.

1. Login to NetBrain API server and get session 2. Set current domain 3. Delete site 4. Call Commit to commit the change 5. Call GetSiteTree to confirm that all sites are created and devices are set 6. Logout NetBrain API server

API Script



import netbrain_restful_lib import time import urllib3 urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning) user = "NetBrain" pwd = "Netbrain" nb_url = "http(s)://<IP address of NetBrain Web Server>/" headers = {'Content-Type': 'application/json', 'Accept': 'application/json'} tenantName = "Initial Tenant" domainName = "Use Case" ################################################################# # Step 1: Login to NetBrain API server and get session print("Step 1") token = netbrain_restful_lib.loginSession(nb_url, user, pwd) print("Token: "+token) print(netbrain_restful_lib.getTenants(nb_url, token)) print(netbrain_restful_lib.getDomains(nb_url, token)) #Sample results # token : adf5b560-8e9c-4114-87bb-2eed24f0faff # tenantList : [{'tenantId': 'a50af282-fa02-012f-a7f7-e410cc7c29d3', 'tenantName': 'Initial


Tenant'}] # domainList : [{'domainName': 'UseCase', 'domainId': '4f747a8b-71da-404b-a05c-e8505aa14725'}] tenantId = 'fcf8a380-6b11-0fed-1d51-3b4cdef8f238' domainId = '25b66365-1ab8-4fed-90c9-1307a4047c3d' # Step 2: Set current domain print("Step 2") print(netbrain_restful_lib.loginDomain(nb_url, token, tenantId, domainId)) # Sample results # loginDomain: Login successfully! # Step 3: Delete Site print("Step 3") data=[{"sitePath":"My Network/US/CA/Palo Alto"} ] print(netbrain_restful_lib.createSiteTransaction(nb_url, token)) for i in data: print(i['sitePath']) print(netbrain_restful_lib.deleteSite(nb_url, token, i['sitePath'])) # Sample results # CreateSiteTransaction: Site transaction created! # DeleteSite: Deleted successfully! # Step 4: Call Commit to commit the change print("Step 4") print(netbrain_restful_lib.commitSiteTransaction(nb_url, token)) # Sample results # CommitSiteTransaction: Site commit True # Step 5: Call GetSiteTree to confirm that all sites are created and devices are set print("Step 5") print(netbrain_restful_lib.getChildSites(nb_url, token, None, "My Network")) for i in data: print(netbrain_restful_lib.getSiteInfo(nb_url, token, None, i['sitePath'])) print(netbrain_restful_lib.getSiteDevice(nb_url, token, None, i['sitePath'])) # Sample results # GetChildSites: [{'siteId': 'aac212cb-fa84-4ddd-8c0b-18a00ec9c323', 'isContainer': False, 'siteType': 2, 'sitePath': 'My Network/NA/US/MA'}, {'siteId': '3ebb978f-323a-4308-8b38-82fa1a0a135f', 'isContainer': False, 'siteType': 2, 'sitePath': 'My Network/NA/US/CA'}] # GetSiteInfo: {'isContainer': True, 'siteId': 'ede2ed2b-d5cf-48dd-b341-020330757033', 'sitePath': 'My Network/NA/US', 'siteType': 1} # GetSiteDevice: [{'mgmtIP': '172.16.8.186', 'id': '06840b62-8a67-4cb2-9ed4-e540ea36fdcf', 'hostname': 'NBUSMA-SW7'}, {'mgmtIP': '172.16.8.194', 'id': '0b152c13-34e0-474e-aa4c-b07fe71cc0b7', 'hostname': 'NBUSMA-R1'}] # Step 6: Logout Netbrain API server print("Step 6") print(netbrain_restful_lib.logoutSession(nb_url, token))


1.18.3. Use Case - Return Hop List of a Path in Third-party System

In a third-party system that supports scripts, you can test the end-to-end path reachability via NetBrain APIs. If path calculation succeeds, the whole hop list of the path will be returned; if path calculation failed, the failure

result and failure point will be returned.

Workflow

The pseudo-code below describes the main flow in the API script to return hop list of a path.

1. Login into NetBrain session and get system token. 2. Set the operation tenant and domain. 3. Get the default gateway information of Source IP. 4. Calculate Path and get task ID. 5. Query path information based on the task ID. 6. Logout the session.

API Script



import netbrain_restful_lib as api nb_url = "http(s)://<IP address of NetBrain Web Server>/" user = "NetBrain" pwd = "Netbrain" tenantName ='Initial Tenant' domainName = 'Integration' # Step1: Login into NetBrain session and get system token. token = api.loginSession(nb_url, user, pwd) print(api.getTenants(nb_url, token)) print(api.getDomains(nb_url, token)) # [{'tenantId': 'cb36f82b-4126-2fef-5310-c3a66f3dae4d', 'tenantName': 'Initial Tenant'}, # {'tenantId': '1aae7b92-520f-4d22-96ed-9ccc77ab5678', 'tenantName': 'TenantName'}] # [{'domainId': '6f9be63d-2290-4121-ae8b-c8fdb53a56ec', 'domainName': 'Integration'}] tenantId = "cb36f82b-4126-2fef-5310-c3a66f3dae4d" domainId = "6f9be63d-2290-4121-ae8b-c8fdb53a56ec" # Step2: Set the operation tenant and domain. print(api.loginDomain(nb_url, token, tenantId, domainId)) # loginDomain: Login successfully! # Step3: Get the default gateway information of Source IP. sourceIP = "10.30.8.108" api.GetGatewayInfo(nb_url, token, sourceIP)


# [{'ip': '10.30.8.105', 'devName': 'HSRP', 'intfName': '21'}, # {'ip': '10.30.8.106', 'devName': 'NBCNBJ-SW1', 'intfName': 'Vlan2100'}, # {'ip': '10.30.8.107', 'devName': 'NBCNBJ-SW2', 'intfName': 'Vlan2100'}] # Step4: Calculate Path and get task ID. sourcePort = 80 sourceGwIP = "10.30.8.105" sourceGwDev = "HSRP" sourceGwIntf = "21" destIP = "10.30.7.108" destPort = 80 pathAnalysisSet = 1 protocol = 4 isLive = False path_param={ "sourceIP":sourceIP, # IP address of the source device. "sourcePort":sourcePort, # TCP/UDP protocol port, such as 23 for telnet. This parameter can be null. "sourceGwDev":sourceGwDev, # Hostname of the gateway device. "sourceGwIP":sourceGwIP, # Ip address of the gateway device. "sourceGwIntf":sourceGwIntf, # Name of the gateway interface. "destIP":destIP, # IP address of the destination device. "destPort":destPort, # TCP/UDP protocol port, such as 23 for telnet. This parameter can be null. "pathAnalysisSet":pathAnalysisSet, # 1:L3 Path; 2:L2 Path; 3:L3 Active Path "protocol":protocol, # Specify the application protocol, check online help, such as 4 for IPv4. "isLive":isLive # False: Current Baseline; True: Live access } api.CalPath(nb_url, token, path_param) # Path task ID: ab3f5241-24db-4b9a-bf3c-1def89fb4599 # Step5: Query path information based on the task ID. taskID = "ab3f5241-24db-4b9a-bf3c-1def89fb4599" api.GetPathResult(nb_url, token, taskID) # [{'hopId': '5e9b740e-16f9-41a5-9fe3-928479110cbe', 'srcDeviceName': '10.30.8.108', 'inboundInterface': '', 'mediaName': '10.30.8.104/29\r\nHSRP: 21(10.30.8.105)', 'dstDeviceName': 'NBCNBJ-SW1', 'outboundInterface': 'Vlan2100', 'nextHopIdList': ['a144f294-4311-445e-9aff-a80f3562e8a0']}, # {'hopId': 'a144f294-4311-445e-9aff-a80f3562e8a0', 'srcDeviceName': 'NBCNBJ-SW1', 'inboundInterface': 'Vlan1', 'mediaName': '10.30.8.24/29', 'dstDeviceName': 'NBCNBJ-SRX2', 'outboundInterface': 'reth1.0', 'nextHopIdList': ['0d436e76-43e3-4620-bd96-3c88007feb88']}, # {'hopId': '0d436e76-43e3-4620-bd96-3c88007feb88', 'srcDeviceName': 'NBCNBJ-SRX2', 'inboundInterface': 'reth0.0', 'mediaName': '10.30.8.16/29', 'dstDeviceName': 'NBCNBJ-R1', 'outboundInterface': 'ge-0/0/2.0', 'nextHopIdList': ['ca4107dc-5b44-4892-9ba1-c4094917d857']}, # {'hopId': 'ca4107dc-5b44-4892-9ba1-c4094917d857', 'srcDeviceName': 'NBCNBJ-R1', 'inboundInterface': 'ge-0/0/1.10', 'mediaName': '10.30.7.32/29', 'dstDeviceName': 'AT&T-AS7018', 'outboundInterface': 'ge-0/0/1.10-10.30.7.33', 'nextHopIdList': ['8e4982de-f53b-41cc-bdcd-58c22c63e81b']}, # {'hopId': '8e4982de-f53b-41cc-bdcd-58c22c63e81b', 'srcDeviceName': 'AT&T-AS7018', 'inboundInterface': 'FastEthernet1/0.10-10.30.7.17(blue)', 'mediaName': '10.30.7.16/29\r\nVRF:blue', 'dstDeviceName': 'NBUSMA-R1', 'outboundInterface': 'FastEthernet1/0.10', 'nextHopIdList': ['c263e983-f247-4d06-8497-6c0d12c8ca19']},


# {'hopId': 'c263e983-f247-4d06-8497-6c0d12c8ca19', 'srcDeviceName': 'NBUSMA-R1', 'inboundInterface': 'FastEthernet2/0', 'mediaName': '10.30.7.104/29', 'dstDeviceName': 'NBUSMA-R2', 'outboundInterface': 'FastEthernet2/0', 'nextHopIdList': []}, # {'hopId': 'ea019ad9-1b18-4658-8d22-cf7b41dbc6ad', 'srcDeviceName': '10.30.8.108', 'inboundInterface': '', 'mediaName': '10.30.8.104/29\r\nHSRP: 21(10.30.8.105)', 'dstDeviceName': 'NBCNBJ-SW2', 'outboundInterface': 'Vlan2100', 'nextHopIdList': ['80ec41b1-d4b4-4f84-b18f-335e22aa6937']}, # {'hopId': '80ec41b1-d4b4-4f84-b18f-335e22aa6937', 'srcDeviceName': 'NBCNBJ-SW2', 'inboundInterface': 'Vlan1', 'mediaName': '10.30.8.24/29', 'dstDeviceName': 'NBCNBJ-SRX2', 'outboundInterface': 'reth1.0', 'nextHopIdList': ['0d436e76-43e3-4620-bd96-3c88007feb88']}] # Step6: Logout the session. print(api.logoutSession(nb_url, token)) # Session logout successfully!

netbrain integrated edition api and system integration guide · netbrain restful apis the system...

Documents