API User Guide. NetBrain Integrated Edition 7.1

Transcription

1 NetBrain Integrated Edition 7.1 API User Guide Version 7.1a Last Updated Copyright NetBrain Technologies, Inc. All rights reserved.

2 Contents 1. RESTful API Authentication and Initialization 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 Discovery Get all 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 status of a discovery task Get the results of discovered devices Get the live access logs of devices Device Information Get all devices in a domain Get the value of a device attribute Get all interfaces of a device Get the value of an interface attribute Get all modules of a device Get the value of a module attribute... 29

3 Get the neighbors of a device by topology type Get the connected switch ports of an end system Get device configuration Device Management Get devices in a device group Get the Front Server of a device Remove devices from a domain in batch Get device group list Attribute Management 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 Site Information Get the basic information of a site Get child sites of a specific site Get devices in a specific site Site Modification Create a transaction to start site modification Remove a site transaction Keep transaction alive Create a parent site... 51

4 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 Path Calculate a Path Get Path Calculation Result Get the gateway information of a device Stop a path Get path calculation status System Management 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... 73

5 1.10. Topology Building Build L2 topology Build L3 topology Get the status of topology building Get One-IP Table Network Settings Add network credentials Edit network credentials Delete network credentials Map Export a map Delete a map Get the file list Get device groups Benchmark 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 run records of a benchmark task Tuning Devices Tune devices Get the results of tuning devices Users Add users Update users

6 Delete users Get the usage report of users Get user information API Status Code List Device Type and ID Best Practices and Use Cases for NetBrain Rest APIs Best Practice to Use NetBrain as CMDB via APIs Use Case - Manage Your NetBrain Data via APIs Use Case - Return Hop List of a Path in Third-party System

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 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 NetBrain Integrated Edition 7.1a API User Guide 7

8 Category API Lists 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 8 NetBrain Integrated Edition 7.1a API User Guide

9 Category API Lists Device and Interface Attribute Manage device and interface attributes, Create a customized device attribute Management such as put delete or create an 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 Network Settings Build Layer 2 and Layer 3 topology in a domain. Manage credentials in a network setting. Build L2 topology Build L3 topology Get the running status of a topology building task Get One-IP Table Add network credentials Edit network credentials NetBrain Integrated Edition 7.1a API User Guide 9

10 Category API Lists 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 10 NetBrain Integrated Edition 7.1a API User Guide

11 1.1.1.Log in to get an authentication token Use this API call to get an authentication token and start a session. POST base_url/v1/session No Tip: The base URL is http(s)://<ip address of your NetBrain Web API Server>/ServicesAPI/API. 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. "username": "NetBrain", "password": "NetBrain" 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. Note: The content type that NetBrain APIs support is application/json. token string The returned authentication token. statuscode integer "token": "301ebdd d The returned status code of executing the c51b8db7f5f0", API. "statuscode": "790200", "status": "Success" status 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. NetBrain Integrated Edition 7.1a API User Guide 11

12 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 Input the token received from the API Log in to get an authentication token. Example: "token": "301ebdd d-8807-c51b8db7f5f0" tenants list A list of all accessible tenants. tenantid string The tenant ID. "tenants": [ tenant string The tenant name. "tenantid": "3e75247a-309c a5-823b6cb1e78d", "tenant": "bos_office" statuscode integer The returned status code of executing the API., "tenantid": "5a75247a-309c status string The explanation of the status code. 96a5-823b6cb1e78d", "tenant": "ny_office" ] 12 NetBrain Integrated Edition 7.1a API User Guide

13 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 tenantid (query) Input the token received from the API Log in to get an authentication token. Input the ID of the tenant that you want to get its domains. Get a tenant ID via the API get all accessible tenants. domains list A list of all accessible domains. domainid string The domain ID. "domains": [ domain string The domain name. "domainid": "4e75247a-309c a5-823b6cb1e78d", "domain": "domain1" statuscode integer The returned status code of executing the API., "domainid": "5e75247a-309c status string The explanation of the status code. 96a5-823b6cb1e78d", "domain": "domain2" ] NetBrain Integrated Edition 7.1a API User Guide 13

14 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 Request *required (body) Input the token received from the API Log in to get an authentication token. The body contains two parameters: 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 Example: accessible domains of a tenant. "tenantid": "3e75247a-309c a5-823b6cb1e78d", "domainid": "4e75247a-309c a5-823b6cb1e78d" statuscode integer The returned status code of executing the status string API. The explanation of the status code. "status": "success" Log out from a session Use this API to log out from the current session. 14 NetBrain Integrated Edition 7.1a API User Guide

15 DELETE /V1/Session Yes Example body *required (body) The body contains one parameter: token*(string): input the token received from login. "token": "301ebdd d c51b8db7f5f0" statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 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 NetBrain Integrated Edition 7.1a API User Guide 15

16 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 tasks list A list of all discovery tasks. id string The ID of a discovery task. "status": "success", name string The name of a discovery task. "tasks": [ enable bool Whether a discovery task is enabled. "id": "1696faa7-749c-78a7-eaadfcf815b11e4a", laststatus string "name": "Scheduled System The last run (result) status of a discovery Discovery", task. "enable": true, lastrunspan integer The duration of the last run of a discovery task. "laststatus": "", "lastrunspan": "00:00:00", "curstatus": "Not Started", "nextruntime": "1/2/3000,12:00:00 curstatus string The current status of a discovery task. AM", nextruntime string The start time of the next run of a discovery task. "frequency": "Once", frequency string The run frequency of a discovery task. "id": "1696faa7-749c-78a7-eaadfcf815b11e4b", statuscode integer The returned status code of executing the API. "name": "Scheduled Discovery1", "enable": true, "laststatus": "", 16 NetBrain Integrated Edition 7.1a API User Guide

17 status string The explanation of the status code. AM", ] "lastrunspan": "00:00:00", "curstatus": "Not Started", "nextruntime": "2/2/3000,12:00:00 "frequency": "Once" 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 task *required (path) Request *required (body) 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 user (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. NetBrain Integrated Edition 7.1a API User Guide 17

18 Example: 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. "seeds": [ "mgmtip": "string", "clitype": 0, "user": "NetBrain", "password": "NetBrain", "privilegeusername": "string", "privilegepassword": "string", "designatedcredentials": true, "snmpcommunitystring ": "string", "frontserverorgroupalias": "string" ] statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 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 18 NetBrain Integrated Edition 7.1a API User Guide

19 task *required (path) Request *required (body) 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: IPs (list): A list with IPs that you want to remove. Example: "IPs": [ " " ] statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 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 task *required (path) 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. NetBrain Integrated Edition 7.1a API User Guide 19

20 IPs list A list with all seed IPs. statuscode integer The returned status code of executing the status string API. The explanation of the status code. "IPs": [ " " ], "status": "success" Run a discovery task now Use this API to run a scheduled discovery task right away. POST /V1/CMDB/Discovery/Tasks/task/Run Yes task *required (path) 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. statuscode integer The returned status code of executing the status string API. The explanation of the status code. "status": "success" 20 NetBrain Integrated Edition 7.1a API User Guide

21 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 task *required (path) 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. statuscode integer The returned status code of executing the API. status string The explanation of the status code. 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. "status": "success", "taskstatus": 10 NetBrain Integrated Edition 7.1a API User Guide 21

22 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 task *required (path) IPs (query) 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. The list of IPs of discovered devices. Returns results of all devices if not specified. Devices list A list of discovered devices. domainid string The ID of the domain that a device belongs to. "status": "success", "devices": [ source string The IP from which a device was discovered. "domainid": "5e75247a-309c a5-823b6cb1e78d", hostname string The hostname of a device. "source": "Scan /32", "hostname": "Bos-Core1", frontserver string The Proxy Server used to discover a device. "frontserver": " ", "ping": "Succeeded", "SNMP": "nb", ping string The ping to a device succeeded or failed. "vendor": "Cisco", "oid": " ", SNMP string The SNMP community string of a device. "type": "Cisco IOS Switch", "config": "Succeeded", vendor string The vendor of a device. "telnetssh": "Succeeded" oid string The OID of a device. 22 NetBrain Integrated Edition 7.1a API User Guide

23 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. statuscode integer The returned status code of executing the API. ] status string The explanation of the status code 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 task *required (path) IPs (query) 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. The list of IPs of discovered devices. Returns live logs of all devices if not specified. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": devices list A list of discovered devices. "success", "devices": [ NetBrain Integrated Edition 7.1a API User Guide 23

24 mgmtip string The management IP of a device. livelogs string The live logs of a device. ] "mgmtip": " ", "livelogs": "xxx" 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 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 24 NetBrain Integrated Edition 7.1a API User Guide

25 hostname (query) ip (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. 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. devices list A list with of devices in a domain. id string The ID of a device. "status": "success", mgmtip string The management IP of a device. "devices": [ hostname string The hostname of a device. "id": "7d47c791-84cb-4bdb-9d2cabbfafe71b2e", devicetypename string The device type of a device. "mgmtip": " ", "hostname": "Bos-Core", "devicetype": "Cisco Router" statuscode integer The returned status code of executing the API. ] status string The explanation of the status code 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 NetBrain Integrated Edition 7.1a API User Guide 25

26 attribute (query) hostname *required (query) The name of the attribute that you want to get value. If not specified, return all attributes and their values. The hostname of a device. Attributes Object An attribute set. attribute string The name of the attribute with its value returned. hostname string The hostname of the returned device. statuscode integer The returned status code of executing the API. "hostname": "BJ-R1", "attributes": "mgmtip": " ", "status": "Success." status string The explanation of the status code Get all interfaces of a device Use this API to get all interfaces of a device. GET /V1/CMDB/Interfaces Yes hostname *required (query) The hostname of a device. 26 NetBrain Integrated Edition 7.1a API User Guide

27 Interfaces list A list of interface names. statuscode integer The returned status code of executing the API. "status": "success", "interfaces": [ "Ethernet 0/1","Ethernet 0/2", status string The explanation of the status code. "Ethernet 0/3" ] 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 hostname *required (query) interface *required (query) attribute (query) The hostname of a device. 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. hostname string The hostname of the returned device. interface string The full name of the target interface. interfaceattributevalue string The returned attribute value. "status": "success", "hostname": "Bos-Core-1", "interface": "XX", NetBrain Integrated Edition 7.1a API User Guide 27

28 statuscode integer The returned status code of executing the API. status string The explanation of the status code. "interfaceattributevalue": "XX" Applicable Interface Attributes Attribute Display in Device Details Pane 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 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. inacl Inbound ACL The inbound ACL of an interface. outacl 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. 28 NetBrain Integrated Edition 7.1a API User Guide

29 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 hostname *required (query) The hostname of a device. Modules list A list of all modules. statuscode integer The returned status code of executing the status string API. The explanation of the status code. "status": "success", "modules": [ "module1","module2", "module3" ] 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 NetBrain Integrated Edition 7.1a API User Guide 29

30 module *required (query) hostname *required (query) attribute (query) The module name of a device. The hostname of a device. The name of the attribute that you want to get it value. If not specified, return all attributes and their values. hostname string The hostname of the returned device. attribute string The name of the attribute. moduleattributevalue integer The value of the attribute. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success", "hostname": "Bos-Core-1", "attribute": "XX", "moduleattributevalue": "XX" 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 hostname *required (query) The hostname of a device. 30 NetBrain Integrated Edition 7.1a API User Guide

31 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. neighbors list A list of returned neighbors. hostname string The hostname of the neighbor device. "status": "success", interface string The name of the neighbor interface. "neighbors": [ statuscode integer The returned status code of executing the API. "hostname": "Bos-Core1", "interface": "FastEthernet0/ /28" status string The explanation of the status code. ] 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 ip *required (path) The IP address of a device interface. NetBrain Integrated Edition 7.1a API User Guide 31

32 hostname list The hostname of the device that the end system connects to. interface string The interface that the end system connects to. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success", "hostname": "Bos-SW", "interface": "Ethernet 0/1" Get device configuration Use this API to get the configuration of a device. GET /V1/CMDB/DataEngine/DeviceData/Configuration Yes Parameter hostname *required (query) The hostname of the device that you want to get the configuration. configuration string The full context of the configuration of the device. time string The last update time of the device configuration. statuscode integer The returned status code of executing the API. status string The explanation of the status code. 'configuration': '!\r\n! This config file is generated via SNMP\r\n!\r\n! vendor,model,sysoid:**cisco**2611** **\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 \r\n!\r\n\r\n interface Tu \r\n description DMVPN shutdown Interface testing\r\n 32 NetBrain Integrated Edition 7.1a API User Guide

33 ip address \r\n!\r\n\r\n', 'time': ' T08:55:28Z', 'statuscode': , 'status': '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 Get devices in a device group Use this API to get the devices in a device group. GET /V1/CMDB/Devices/GroupDevices/group Yes group *required (path) The name of a device group. NetBrain Integrated Edition 7.1a API User Guide 33

34 devices list A list of devices. id string The device ID. "devices": [ "id": "967cadf3-f4e e8- mgmtip string The management IP address of the returned a9ead ", device. "mgmtip": " ", "hostname": "BST-POP1" hostname string The hostname of returned device. ] 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 hostname *required (path) The hostname of a device. alias string The alias of the Front Server. iporhostname string The IP address or name of the Front Server. statuscode string The returned status code of executing the API. "alias": "Front Server Alias", "iporhostname": "Bos-Core", "status": "success" status string The explanation of the status code. 34 NetBrain Integrated Edition 7.1a API User Guide

35 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 Request *required (body) 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. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Get device group list Use this API to get all device group lists in a domain. GET /V1/CMDB/DeviceGroups Yes NetBrain Integrated Edition 7.1a API User Guide 35

36 Place the token received from login. devicegroups list A list of all accessible domains. id string The ID of a device group "devicegroups": [ name string The name of a device group "id":" b-b223-4bc ac4da95b1695", type integer The type of a device group. 0: Public 1: Private 2: System "name":"#bgp 64512", "type":2, "id":"fbd027f2-24c a6bd-62b7613b07e1", "name":"#bgp 65000", "type":2, "id":"fcdb1b8b-bffd-478fa914-e867f6a87f86", "name":"retest", "type":0 ], "statuscode":790200, "status":"success." 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 36 NetBrain Integrated Edition 7.1a API User Guide

37 Set value for a specified module attribute Delete a module attribute Create a customized device attribute Use this API to create a customized device attribute for certain device types. POST /V1/CMDB/Devices/Attributes Yes Request *required (body) The body contains the following parameters: attribute*(string): the name of the attribute to be created. attributedisplay (string): the display name of the attribute in Device Details pane of NetBrain system. devicetypes*(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 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 Example: extended search and default search. "attribute": "newattribute", "attributedisplay": "New Attribute", "devicetypes": "null", "datatype": "string", "subdatatype": "null", "isfullsearch": true NetBrain Integrated Edition 7.1a API User Guide 37

38 statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 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 Request *required (body) The body contains the following parameters: attribute*(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: "attribute": "loc", "attributevalue": "Boston", "hostname": "Bos-Core1" statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 38 NetBrain Integrated Edition 7.1a API User Guide

39 1.5.3.Delete a device attribute Use this API to delete an attribute of a device. DELETE /V1/CMDB/Devices/Attributes/attribute Yes attribute *required (path) The name of the attribute that you want to delete. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Create a customized interface attribute Use this API to create a customized interface attribute for certain device types. POST /V1/CMDB/Interfaces/Attributes Yes NetBrain Integrated Edition 7.1a API User Guide 39

40 Request *required (body) The body contains the following parameters: attribute*(string): the name of the interface attribute to be created. attributedisplay (string): the display name of the attribute in the Device Details pane of NetBrain system. devicetypes*(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 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). 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 Example: extended search and default search. "InterfaceType": "ipintfs ", "attribute": "newattribute", "attributedisplay": "New Attribute", "devicetypes": "null", "datatype": "string", "subdatatype": "null", "isfullsearch": true statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Set value for a specified interface attribute Use this API to set a value for a specified attribute of an interface. 40 NetBrain Integrated Edition 7.1a API User Guide

41 PUT /V1/CMDB/Interfaces/Attributes Yes Request *required (body) The body contains the following parameters: attribute*(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. interface*(string): the full name of the interface. Example: "attribute": "loc", "attributevalue": "Boston", "hostname": "Bos-Core1", "interface": "Ethernet0/1" statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Delete an interface attribute Use this API to delete an attribute of an interface. DELETE /V1/CMDB/Interfaces/Attributes Yes NetBrain Integrated Edition 7.1a API User Guide 41

42 attribute *required The name of the attribute that you want to delete. (query) 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). statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Create a customized module attribute Use this API to create a customized module attribute for certain device types. POST /V1/CMDB/Modules/Attributes Yes Request *required (body) The body contains the following parameters: attribute*(string): the name of the module attribute to be created. attributedisplay (string): the display name of the attribute in the Device Details pane of NetBrain system. devicetypes*(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 and ID for available device types. datatype*(string): the supported data types of the attribute, such as string. 42 NetBrain Integrated Edition 7.1a API User Guide

43 subdatatype (string): this parameter is only available to the attribute in list or table type. isfullsearch*(boolean): set whether to use the attribute as an index in full scope search, including Example: extended search and default search. "attribute": "newattribute", "attributedisplay": "New Attribute", "devicetypes": "null", "datatype": "string", "subdatatype": "null", "isfullsearch": true statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 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 Request *required (body) The body contains the following parameters: attribute*(string): the name of the attribute to set value. attributevalue*(string): the value to set for the attribute. NetBrain Integrated Edition 7.1a API User Guide 43

44 hostname*(string): the hostname of the device. module*(string): the full name of the module. Example: "attribute": "", "attributevalue": "Boston", "hostname": "Bos-Core1", "module": "slot1" statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Delete a module attribute Use this API to delete an attribute of a module. DELETE /V1/CMDB/Modules/Attributes Yes body *required (body) The body contains one parameter: attribute: the name of the attribute that you want to delete. 44 NetBrain Integrated Edition 7.1a API User Guide

45 statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 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 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 sitepath *required (query) The full path of a site, such as My Network/NA/US. siteinfo object An object with the basic information of a site. "siteinfo": [ NetBrain Integrated Edition 7.1a API User Guide 45

46 siteid string The site ID. 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, "siteid": "1da4fda8-5d04-491b-8bb0-2e9abb989a60", "sitepath": "My Network/NA/US", "iscontainer": true, "sitetype": 0 ] 2: leaf site 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 sitepath *required (query) siteid (query) The full path of a site, such as My Network/NA/US. The site ID. siteinfo list A list of all child sites. siteid string The site ID. "siteinfo": [ sitepath string The full path of a site. "siteid": "1da4fda8-5d04-491b-8bb0-2e9abb989a60", 46 NetBrain Integrated Edition 7.1a API User Guide

47 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 Get devices in a specific site Use this API to get all devices in a site. GET /V1/CMDB/Sites/Devices Yes sitepath *required (query) The full path of a site, such as My Network/NA/US. devices object An object with all devices in a site. Id string The ID of a device "devices": [ mgmtip string The management IP of a device. "id": "7d47c791-84cb-4bdb-9d2cabbfafe71b2e", hostname string The hostname of a device. "mgmtip": " ", "hostname": "GW2Lab", "devicetype": "Cisco IOS Switch" NetBrain Integrated Edition 7.1a API User Guide 47

48 ] 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. 48 NetBrain Integrated Edition 7.1a API User Guide

49 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 statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Remove a site transaction Use this API to remove a transaction. DELETE /V1/CMDB/Sites/Transactions Yes NetBrain Integrated Edition 7.1a API User Guide 49

50 statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 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 50 NetBrain Integrated Edition 7.1a API User Guide

51 statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Create a parent site Use this API to create a parent site. POST /V1/CMDB/Sites/Parent Yes Request *required (body) The body contains one parameter: sitepath * (string): the full path of a site, such as My Network/Site1/Boston. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Create a leaf site Use this API to create a leaf site. NetBrain Integrated Edition 7.1a API User Guide 51

52 POST /V1/CMDB/Sites/Leaf Yes Request *required (body) The body contains one parameter: sitepath * (string): the full path of a site, such as My Network/Site1/Boston. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 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 Request *required (body) The body contains two parameters: sitepath * (string): the full path of a site, such as My Network/Site1/Boston. iscontainer * (bool): specify whether the site to be added is a container site. 52 NetBrain Integrated Edition 7.1a API User Guide

53 Example: "sites": [ "sitepath": "string", "iscontainer": true, "sitepath": "string", "iscontainer": false, ] statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Delete a site Use this API to delete a site. DELETE /V1/CMDB/Sites Yes sitepath *required (query) The full path of the site to be deleted. NetBrain Integrated Edition 7.1a API User Guide 53

54 statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Add devices to a site Use this API to add devices to a site. POST /V1/CMDB/Sites/Devices Yes Request *required (body) The body contains two parameters: 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" ] statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 54 NetBrain Integrated Edition 7.1a API User Guide

55 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 Request *required (body) The body contains two parameters: sitepath * (string): the full path of a site. Devices * (list): the devices to be added. Example: "sitepath": "XXXXXXX", "Devices": [ "Bos-Core1" ] statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Remove devices from a site Use this API to remove devices from a site. NetBrain Integrated Edition 7.1a API User Guide 55

56 DELETE /V1/CMDB/Sites/Devices Yes Request *required (body) The body contains two parameters: sitepath * (string): the full path of a site. Devices * (list): the devices to be deleted. Example: "sitepath": "XXXXXXX", "Devices": [ "Bos-Core1" ] statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Commit modifications to rebuild a site Use this API to commit all site change operations and rebuild sites. PUT /V1/CMDB/Sites/Transactions Yes 56 NetBrain Integrated Edition 7.1a API User Guide

57 rebuildsite *required (body) (bool) Choose whether to rebuild sites. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 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 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 NetBrain Integrated Edition 7.1a API User Guide 57

58 body *required (body) The body contains the following parameters: 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. Example: o 0: use data from the current baseline. o 1: use data via live access. "sourceip": " ", "sourceport": 0, "sourcegwip": " ", "sourcegwdev": "GW2Lab", "sourcegwintf": "GigabitEthernet0/0.10", "destip": " ", "destport": 0, "pathanalysisset": 1, "protocol": 4, "islive": 1 taskid string The ID of the task. statuscode integer The returned status code of executing the status string API. The explanation of the status code. "taskid": "string", "status": "success" 58 NetBrain Integrated Edition 7.1a API User Guide

59 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 taskid *required (path) The task ID returned in the Calculate a Path API. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success", "hoplist": [ hoplist list A list of hops along a path. "hopid": "string", hopid string The ID of a hop. "srcdevice": "string", "inboundinterface": "string", srcdevice string The hostname of the source device. "media": "string", "dstdevice": "string", inboundinterface string The name of the inbound interface. "outboundinterface": "string", "nexthopidlist": [ media string The media name. "7a09854d-1d a7b142fccb75" dstdevice 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. NetBrain Integrated Edition 7.1a API User Guide 59

60 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 iporhost *required (query) The IP or hostname of a device. gatewaylist list A list of returned gateway devices. The list contains the following subparameters: ip (string): the IP address of a gateway. dev (string): the hostname of a gateway. Intf (string): the name of the gateway interface. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success", "gatewaylist": [ "ip": "string", "dev": "string", "intf": "string" ] Stop a path Use this API to stop a path in the calculation. 60 NetBrain Integrated Edition 7.1a API User Guide

61 Post /V1/CMDB/Path/Calculation/Stop Yes taskid *required (query) Place the token received from login. The task ID returned in the Calculate a Path API. statuscode integer The returned status code of executing the status string API. The explanation of the status code. result bool The result of stopping a path. "result": true, "status": "Success." Get path calculation status Use this API to get the status of a path. GET /V1/CMDB/Path/taskID/Status Yes taskid *required (query) Place the token received from login. The task ID returned in the Calculate a Path API. NetBrain Integrated Edition 7.1a API User Guide 61

62 statuscode integer The returned status code of executing the API. status string The explanation of the status code. resultcode integer The status code of a path. 0: Initialized 1: Running 2: Succeeded 3: Failed 4: Canceled result string The explanation of the result code. "statuscode":790200, "status":"success", "result": "resultcode":1, "result":"running" 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 Add a tenant Use this API to add a tenant. 62 NetBrain Integrated Edition 7.1a API User Guide

63 POST /V1/CMDB/Tenants Yes Request *required (body) The body contains the following parameters: tenant*(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: "tenant": "Tenant", "description": "", "maximumnodes": "5" tenantid string The ID of the tenant. statuscode integer The returned status code of executing the API. "status": "string", "tenantid": "3e75247a-309c a5- statusdescriptio string The explanation of the status code. 823b6cb1e78d" n Update a tenant Use this API to update a tenant. NetBrain Integrated Edition 7.1a API User Guide 63

64 PUT /V1/CMDB/Tenants Yes Request *required (body) The body contains the following parameters: tenantid*(string): the name of the tenant that you want to update. tenant (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. 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: "tenantid": "4e75247a-309c a5-823b6cb1e78d", "tenant": "Tenant", "description": "", "maximumnodes": "5" statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Delete a tenant Use this API to delete a tenant. 64 NetBrain Integrated Edition 7.1a API User Guide

65 DELETE /V1/CMDB/Tenants/tenantId Yes tenantid *required (path) The ID of the tenant that you want to delete. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Assign users to a tenant Use this API to assign users to a tenant. POST /V1/CMDB/Tenants/Users Yes Request *required (body) The body contains the following parameters: 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. NetBrain Integrated Edition 7.1a API User Guide 65

66 Example: "tenantid": "4e75247a-309c a5-823b6cb1e78d", "users": "username": "NetBrain", "istenantadmin": "NetBrain" statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Add a domain Use this API to add a domain. POST /V1/CMDB/Domains Yes Request *required (body) The body contains the following parameters: tenantid*(string): the ID of the tenant that the created domain belongs to. domain*(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. 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. 66 NetBrain Integrated Edition 7.1a API User Guide

67 Example: "tenantid": "4e75247a-309c a5-823b6cb1e78d", "domain": "domain", "description": "", "maximumnodes": "5" domainid string The ID of the domain. statuscode integer The returned status code of executing the API. "status": "string", "domainid": "5e75247a-309c a5-823b6cb1e78d" status string The explanation of the status code Update a domain Use this API to update a domain. PUT /V1/CMDB/Domains Yes Request *required (body) The body contains the following parameters: domainid*(string): the name of the domain that you want to update. domain (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. NetBrain Integrated Edition 7.1a API User Guide 67

68 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: "domainid": "5e75247a-309c a5-823b6cb1e78d", "domain": "Tenant", "description": "", "maximumnodes": "5" statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Delete a domain Use this API to delete a domain. PUT /V1/CMDB/Domains/domainId Yes domainid *required (path) The ID of the domain that you want to delete. statuscode integer The returned status code of executing the API. 68 NetBrain Integrated Edition 7.1a API User Guide

69 status string The explanation of the status code. "status": "success" Assign users to a domain Use this API to assign users to a domain. POST /V1/CMDB/Domain/Users Yes Request *required (body) The body contains the following parameters: 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: Example: o username*(string): the name of a user. o roles: the roles of a user, such as admin, guest, and engineer. "domainid": "3e75247a-309c a5-823b6cb1e78d", "users": "username": "NetBrain", "roles": "guest" NetBrain Integrated Edition 7.1a API User Guide 69

70 statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Remove users from a domain Use this API to remove users from a domain. DELETE /V1/CMDB/Domain/Users Yes Request *required (body) The body contains the following parameters: 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 a5-823b6cb1e78d", "users": "user1","user2" " statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 70 NetBrain Integrated Edition 7.1a API User Guide

71 Add a role Use this API to add a role and grant privileges to the role. POST /V1/CMDB/Roles Yes Request *required (body) The body contains the following parameters: role*(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: "role": "Role ", "description": "string", "privileges": "string" statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Update a role Use this API to update a role and its privileges. NetBrain Integrated Edition 7.1a API User Guide 71

72 PUT /V1/CMDB/Roles Yes Request *required (body) The body contains the following parameters: newrole (string): a new name of the role. No change will be made if newrole, description, and privileges fields are all null. role*(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: "newrole": "Role ", "role": "Role ", "description": "string", "privileges": "string" statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Delete a role Use this API to delete a role. 72 NetBrain Integrated Edition 7.1a API User Guide

73 DELETE /V1/CMDB/Roles/Rolename Yes role *required (path) The name of the role that you want to delete. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Get role information Use this API to get the information of a role. Get /V1/CMDB/Roles Yes role (query) The name of the role. If null, return the information of all roles. NetBrain Integrated Edition 7.1a API User Guide 73

74 roledata List A list of role information. It statuscode contains the following parameters: role (string): the name of a role. description (string): the description of a role. privileges (list): the privileges of a role. integer The returned status code of executing the API. "status": "success", "RoleData": [ 'role': "networkchangeapprover", 'newrole': None, 'description': ''Network Change Approver', 'privileges': None ] statusdescri ption string The explanation of the status code 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 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 74 NetBrain Integrated Edition 7.1a API User Guide

75 taskid string The task Id. It can be used to query task status. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "taskid": "string", "status": "success" 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 taskid string The task Id. It can be used to query task status. statuscode integer The returned status code of executing the API. "taskid": "string", "status": "success" status string The explanation of the status code Get the status of topology building Use this API to get the status of an L2/L3 topology building task. NetBrain Integrated Edition 7.1a API User Guide 75

76 Get /V1/CMDB/Topology/Tasks/task/Status Yes taskid *required (path) The ID of a topology building task. status string The status of the topology building task. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "finished", "status": "success" Get One-IP Table Use this API to get all IP addresses in the same network segment. Get /V1/CMDB/Topology/OneIPTable Yes ip (string) (query) The IP address that you want to return its One-IP Table items. 76 NetBrain Integrated Edition 7.1a API User Guide

77 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) count (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. Specify the maximum number of returned data. This parameter is required when the IP parameter is specified. oneiplist List A list of One-IP items. ip string The IP address of an end system or device lansegment string interface in a One-IP table item. The LAN segment of the IP address. mac string The MAC address that the IP corresponds to. dev string The name of the device that the IP belongs interfacenam string e switch string to. The name of the interface that the IP belongs to. The name of the switch that the IP connects to. port 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. "status": "success", "OneIPList": [ 'alias': "", 'descr': '"if&ipfor EIGRP"', 'dev': 'SanJose_Core', 'dns': 'SanJose_Core', 'interface': 'Ethernet0/0', 'ip': ' ', 'lansegment': ' /24', 'mac': 'FCFB.FB8C.6288', 'port': 'Ethernet0/0', 'servertype': 2, 'source': 'ARP Table', 'sourcedevice': 'SanJose_Core', 'switch': 'NY_DIS_1', 'switchtype': 2, 'updatetime': ' ', 'userflag': 7, 'vendor': 'Cisco Systems', ] 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. NetBrain Integrated Edition 7.1a API User Guide 77

78 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 Network Settings Use the following APIs to manage credentials in Network Settings. Add network credentials Edit network credentials Delete network credentials Add network credentials Use this API to add a network credential. POST /V1/CMDB/NetworkSettings Yes 78 NetBrain Integrated Edition 7.1a API User Guide

79 Request *required (body) The body contains the following parameters: privatekey (object): used to add a private key. It contains the following subparameters: o alias * (string): the alias of the private key. o key (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 key (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. NetBrain Integrated Edition 7.1a API User Guide 79

80 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 key (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: AES NetBrain Integrated Edition 7.1a API User Guide

81 Example: username (string): the username to access the network devices. context (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. "privatekey": "alias": "string", "key": "string", "md5keycontent": "string", "keycontent": "string", "passwordphrase": "string", "jumpbox": "alias": "string", "ipaddr": "string", "mode": 0, "port": 0, "username": "string", "password": "string", "Key": "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", "user": "string", "password": "string", "climode": 0, "key": "string", "privilegeinfo": "alias": "string", "user": "string", "password": "string", "snmpinfo": "alias": "string", NetBrain Integrated Edition 7.1a API User Guide 81

82 "snmpversion": 0, "rostring": "string", "v3": "authmode": 0, "authpro": 0, "encryptpro": 0, "user": "string", "context": "string", "authpassword": "string", "encryptpassword": "string" statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Edit network credentials Use this API to edit a network credential. PUT /V1/CMDB/NetworkSettings Yes Request *required (body) The body contains the following parameters: privatekey (object): used to add a private key. It contains the following subparameters: 82 NetBrain Integrated Edition 7.1a API User Guide

83 o alias * (string): the alias of the private key. o key (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 key (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. NetBrain Integrated Edition 7.1a API User Guide 83

84 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 key (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. context (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 NetBrain Integrated Edition 7.1a API User Guide

85 Example: "privatekey": "alias": "string", "key": "string", "md5keycontent": "string", "keycontent": "string", "passwordphrase": "string", "jumpbox": "alias": "string", "ipaddr": "string", "mode": 0, "port": 0, "username": "string", "password": "string", "Key": "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", "user": "string", "password": "string", "climode": 0, "key": "string", "privilegeinfo": "alias": "string", "user": "string", "password": "string", "snmpinfo": "alias": "string", "snmpversion": 0, "rostring": "string", "v3": "authmode": 0, "authpro": 0, "encryptpro": 0, "user": "string", "context": "string", NetBrain Integrated Edition 7.1a API User Guide 85

86 "authpassword": "string", "encryptpassword": "string" statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Delete network credentials Use this API to delete a specific network setting. DELETE /V1/CMDB/NetworkSettings Yes Request *required (body) The body contains the following parameters: 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. 86 NetBrain Integrated Edition 7.1a API User Guide

87 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: Example: o alias * (string): the alias of the SNMP credentials that you want to delete. "privatekey": "alias": "string", "jumpbox": "alias": "string", "telnetinfo": "alias": "string", "privilegeinfo": "alias": "string", "snmpinfo": "alias": "string" statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Map Use the following API to export a map to local: Export a map Delete a map NetBrain Integrated Edition 7.1a API User Guide 87

88 Export a map Use this API to export a map into.xmap or.visio from a NetBrain map URL. GET /V1/CMDB/Maps Yes url *required (query) format *required (query) pages (query) The URL of the map that you want to export. The format of the exported map file, such as "xmap", "visio". The name of the map page that you want to export. filedata object Byte stream of xmap in specified format. statuscode string The returned status code of executing the status string API. The explanation of the status code. "filedata": "string", "status": "success" Delete a map Use this API to delete a map from the current domain. 88 NetBrain Integrated Edition 7.1a API User Guide

89 DELETE /V1/CMDB/Maps Yes url *required (query) The URL of the map that you will delete. statuscode string The returned status code of executing the API. status string The explanation of the status code. "status": "success" 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 NetBrain Integrated Edition 7.1a API User Guide 89

90 Body *required (body) Place the token received from login. The body contains the following parameters: 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] items list A list of folders and files. id string The ID of a folder in the Files tree. "items": [ name string The name of a file. "id":"ad09aa07-b31d-4f42- a0aa b09", originalid string For the Map and Dashboard types only. The ID of a specific dashboard or file. "name":"public/site Maps", "type":0, type integer The type of a file. 0: Folder 11: Map 21: Dashboard "originalid":"75ff3cdf-dff4-48c6-a736-7a86e4374a29", "id":"2a19165f-a4a ac5d-acdf9e287ed6", "name":"public/new Folder/New Folder/New Map", "type":11, "originalid":"d2650deb cb-be21-43e2b129380a", "id":"a84cdca b1- b e38fd6d08", "name":"public/new Folder(1)/New Map", "type":11 ], "statuscode":790200, 90 NetBrain Integrated Edition 7.1a API User Guide

91 "status":"success." Get device groups Use this API to get all device group lists in a domain. GET /V1/CMDB/DeviceGroups Yes Place the token received from login. devicegroups list A list of all accessible domains. id string The ID of a device group "devicegroups": [ name string The name of a device group "id":" b-b223-4bc ac4da95b1695", type integer The type of a device group. 0: Public 1: Private 2: System "name":"#bgp 64512", "type":2, "id":"fbd027f2-24c a6bd-62b7613b07e1", "name":"#bgp 65000", "type":2, "id":"fcdb1b8b-bffd-478fa914-e867f6a87f86", "name":"retest", "type":0 ], NetBrain Integrated Edition 7.1a API User Guide 91

92 "statuscode":790200, "status":"success." 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 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 Request *required (body) The body contains the following parameters: task * (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, , or 2017/07/ NetBrain Integrated Edition 7.1a API User Guide

93 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. isbuildipv6l3topo (bool): determine whether to build IPv6 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. NetBrain Integrated Edition 7.1a API User Guide 93

94 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. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Update a benchmark task Use this API to update a benchmark task. Method URL Authentication PUT /V1/CMDB/Benchmark/Tasks Yes Request *required (body) The body contains the following parameters: task * (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, , or 2017/07/13. schedule * (object): the schedule to run the task. The following subparameters are included in this object: 94 NetBrain Integrated Edition 7.1a API User Guide

95 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. isbuildipv6l3topo (bool): determine whether to build IPv6 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. isrecalculatesite (bool): determine whether to rebuild sites. This field is optional and the default value is false. NetBrain Integrated Edition 7.1a API User Guide 95

96 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. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Delete a benchmark task Use this API to delete a benchmark task. Method URL Authentication DELETE /V1/CMDB/Benchmark/Tasks/task Yes task *required (path) The name of the benchmark task you want to delete. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" 96 NetBrain Integrated Edition 7.1a API User Guide

97 Run a benchmark task immediately Use this API to run a benchmark task immediately. Method URL Authentication POST /V1/CMDB/Benchmark/Tasks/task/Run Yes task *required (path) The ID or name of the benchmark task you want to run. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Get the status of a benchmark task Use this API to get the status of a benchmark task. Method URL Authentication GET /V1/CMDB/Benchmark/Tasks/task/Status Yes NetBrain Integrated Edition 7.1a API User Guide 97

98 task *required (path) The ID or name of the benchmark task. taskstatus integer The status of the scheduled task. Possible values: 1: Unknown 0: Never run 2: Running 10: Succeeded "taskstatus": 0, "status": "success" 11: Succeeded with warnings 20: Failed 30: Manually stopped 31: Automatically stopped due to timeout set by users or another system setting. statuscode integer The returned status code of executing the API. status string The explanation of the status code 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. Method URL Authentication GET /V1/CMDB/Benchmark/Tasks/task/Runs Yes task *required (path) The ID or name of the benchmark task. 98 NetBrain Integrated Edition 7.1a API User Guide

99 runs object An object with the historical record of each run. Each execution creates a run record. 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 "runs": [ "runid": "string", "starttime": "string", "endtime": "string", "status": 10, "isfinished": true, "isstopbyuser": true ], "status": "success" 11: Succeeded with warnings 20: Failed 30: Manually stopped 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. statuscode integer The returned status code of executing the API. status string The explanation of the status code 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 NetBrain Integrated Edition 7.1a API User Guide 99

100 Tune devices Use this API to start a task of tuning devices. POST /V1/CMDB/TuneDevices Yes body *required (body) 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. taskid string The task ID of tuning devices. This ID is used to get the results of the tuning task. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "taskid": "string", "status": "Success." Get the results of tuning devices Use this API to get the results of tuning devices. 100 NetBrain Integrated Edition 7.1a API User Guide

101 Get /V1/CMDB/TuneDevices Yes taskid (string) (query) begin (int) (query) count (int) (query) hostnames (list) (query) The task ID of tuning devices. 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. Specify the maximum number of returned data. This parameter is required when the hostnames parameter is not specified. 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. devices list A list of devices that return tuning result. device 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. "devices": [ "device": "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", NetBrain Integrated Edition 7.1a API User Guide 101

102 ping string The ping result. 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. device string The device name. log string The log of tuning a device. statuscode integer The returned status code of executing the API. "status": "Success" status string The explanation of the status code Users Use the following APIs to manage user accounts. Add users Update users Delete users Get the usage report of users Get user information Add users Use this API to create user accounts in the system. POST /V1/CMDB/Users Yes 102 NetBrain Integrated Edition 7.1a API User Guide

103 body *required (body) The body contains the following parameters: username* (string): the username to log into your NetBrain domain. * (string): the address of the user. first* (string): the first name of the user. last* (string): the last name of the user. password* (string): the login password. The allowed length is 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. Example: o tenant (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 domain (string): the domain name. o domainroles(string): the role of the domain user. Specify a tenant for the user. "username": NetBrain, " ": NetBrain@netbrain.com, "first": NetBrain, "last": NetBrain, "password": ******, "authenticationtype": null, "phonenumber": null, "department": null, "description": null, "allowchangepassword": null, "deactivatedtime": null, "issystemadmin": null, "tenants": null NetBrain Integrated Edition 7.1a API User Guide 103

104 statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Update users Use this API to modify user information. PUT /V1/CMDB/Users Yes body *required (body) The body contains the following parameters: username* (string): the username to log into your NetBrain domain. * (string): the address of the user. first* (integer): the first name of the user. last* (integer): the last name of the user. password* (integer): the login password. The allowed length is 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. 104 NetBrain Integrated Edition 7.1a API User Guide

105 tenants (object): specify a list of tenants for the user. Only required if the value of the issystemadmin parameter is false. Example: o tenant (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 domain (string): the domain name. o domainroles(string): the role of the domain user. Specify a tenant for the user. "username": NetBrain, " ": NetBrain@netbrain.com, "first": NetBrain, "last": NetBrain, "password": ******, "authenticationtype": null, "phonenumber": null, "department": null, "description": null, "allowchangepassword": null, "deactivatedtime": null, "issystemadmin": null, "tenants": null statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Delete users Use this API to create user accounts in the system. NetBrain Integrated Edition 7.1a API User Guide 105

106 DELETE /V1/CMDB/Users Yes username *required (path) The name of the user that you want to delete. statuscode integer The returned status code of executing the API. status string The explanation of the status code. "status": "success" Get the usage report of users Use this API to get the usage summary of a domain. Method URL Authentication GET /V1/CMDB/Users/UsageReport Yes tenantid (query) domainid (query) Tenant ID. Domain ID. 106 NetBrain Integrated Edition 7.1a API User Guide

107 fromdate (query) todate (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, T04:59:59Z. The end time. If not specified, use the current time. Format: <yyyy>-<mm>-<dd>t<hh>:<mm>:<ss>z. For example, T04:59:59Z. usagereport object The returned usage report. It contains the statuscode 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. integer The returned status code of executing the API. "status": "success", "usagereport": [ "username": "NetBrain", "oflogins": "string", "firsttimelogin": "string", "lastlogouttime": "string", "totalonlinetime": "string", "ofloginfailureduetoseatlicense": "string" ] status string The explanation of the status code Get user information Use this API to get the user information of a user. Get /V1/CMDB/Users Yes NetBrain Integrated Edition 7.1a API User Guide 107

108 username (query) The name of the user that you get the information. If not specified, the API returns the information of all users. userdata List The returned user information. It contains the following parameters: username: the user name. the address of the user. first: the first name of the user. last: 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, " ": NetBrain@netbrain.com, "first": NetBrain, "last": NetBrain, "password": ******, "authenticationtype": null, "phonenumber": null, "department": null, "description": null, "allowchangepassword": True, "deactivatedtime": null, "issystemadmin": True, "tenantsandroles": null statuscode integer The returned status code of executing the API. status string The explanation of the status code 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. 108 NetBrain Integrated Edition 7.1a API User Guide

109 Service Status Code HTTP Status Code Success Success Created (the result of POST method). Parameter Validation Failure Null parameter Invalid parameter Invalid value Parameter conflict Invalid tenant Invalid domain Non-existing data Data conflict Unsupported feature Null or invalid value Attribute not editable Attribute not supported Built-in attribute deletion error Field name violation Value out of range Alphabet string constraint Character validation failed Invalid address Invalid type The map is not existing Unknown switch Zero or negative value Negative value. NetBrain Integrated Edition 7.1a API User Guide 109

110 Service Status Code HTTP Status Code Unknown source gateway Site transaction not found Site locked Trying to execute an operation that is invalid for a leaf site Trying to execute an operation that is invalid for a container site. Server Exception Unexpected Error Inner exception Task error. Routing Error No routing resource found for given URL The method is not supported for given HTTP request. Task or Operation failure No IP to discover The task is already in running state Run disabled task Task type is not scanned The task is not existing Failed to start a task incomplete task failed task Canceled task Operation conflict Operation failed Task type error, not a benchmark task Task type error, not a discovery task. Authentication Failure and Permission Error Authentication error. 110 NetBrain Integrated Edition 7.1a API User Guide

111 Service Status Code HTTP Status Code Insufficient permissions on tenant or domain No permission to log into the system Insufficient permissions The session expired Invalid token Request timeout Exceeds tenant available node Do not allow resetting passwords Do not allow modifying parameter The session does not exist API calls exceeded the limit No API license or license expired (could be caused by license check failure). External Approval for Change Management The change management failed to bind to a ticket The change management was already bound to another ticket The change management is not allowed to bind to a ticket The change management state is not allowed to be changed Failed to update the change management state License missing or invalid Device Type and ID The following table lists the predefined device types and the corresponding IDs. Type ID Cisco Router 2 Juniper Router 102 End System 1004 NetBrain Integrated Edition 7.1a API User Guide 111

112 Type 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 NetBrain Integrated Edition 7.1a API User Guide

113 Type ID Call Manager 3001 IP Phone 3002 Cache Engine 3003 Cisco WLC 3033 LWAP 3034 Aruba WLC Com Switch 3333 Planet WGSW Aerohive Wireless Dell Networking Switch MikroTik Xirrus Wireless Array Adtran Cisco ACE A10 Load Balancer Fortinet FortiGate Firewall Netscaler Load Balancer Sidewinder Firewall Hirschmann Switch Alcatel Lucent Service Router Alcatel OmniSwitch Radwin Radio Devices Huawei Switch Cisco UCS Fabric MRV RuggedCom ROX Switch Uplogix NetBrain Integrated Edition 7.1a API User Guide 113

114 Type ID SMC Switch Riverbed WAN Optimizer Tellabs Router RuggedCom RS(G) Avaya Switch Dell Sonicwall Casa Tellabs Switch Aruba LWAP Alcatel OmniStack Switch Dlink Switch Cisco WAAS Brocade Vyatta Router Juniper QFabric System SilverPeak WAN Optimizer Aruba IAP Cisco VDS Arris Router Calix E-Series Cisco Meraki AP Adva Optical Cisco Meraki Switch Avaya Router GigaVUE-OS Cisco Meraki Cloud Bluecoat Cisco Meraki Firewall Cisco MDS NetBrain Integrated Edition 7.1a API User Guide

115 Type ID Fujitsu Switch Viptela Redback Router Calix B-Series T-Marc 300 Series Avaya VSP IBM Switch Cisco Firepower Security Appliance Raisecom Switch Crossbeam Firewall Ubiquiti airmax Moxa Switch Big Switch APC APC UPS Stonesoft NGFW Watchguard Firewall Oracle Acme Aruba Switch IBM DataPower Radware Alteon Cisco Firepower NGFW Digi Cellular Router Nexans GigaSwitch VM Host vsphere Standard Switch vsphere Distributed Switch NetBrain Integrated Edition 7.1a API User Guide 115

116 Type ID NSX Distributed Logical Router NSX Edge Security Gateway NSX Manager NSX Controller NSX Logical Switch Cisco ACI APIC Cisco ACI Spine Switch Cisco ACI Leaf Switch Fortinet Controller Managed Switch Fortinet Controller Managed AP 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 116 NetBrain Integrated Edition 7.1a API User Guide

117 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 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 NetBrain Integrated Edition 7.1a API User Guide 117