OpUtils API

    Overview

    OpUtils Application Programming Interface (API) allows you to programmatically connect to the database used by OpUtils to get the required information. While it is also possible to manually connect to the database using ODBC and fetch the information by constructing an SQL query, API eases it by not requiring you to be conversant with the database schema and relationships with various database tables. OpUtils API benefits you in many ways:

    • Get the required information programmatically to be used in other in-house or third-party applications
    • Link it to other third-party reporting tools for customized reporting
    • You do not need to understand how the data is stored in the various database tables and the relationships with other tables/data.

    Using API

    Requests to OpUtils API is via URL, which connects to the OpUtils database and get the required information. The URL construct of the URL should be as below:

    http://<oputils_server_name_or_ip>:<port_number>/oputilsapi/<oputils_module>?v=<api_version>&key=<api_key>&operation=<operation_name>&<operation_parameters>&format=<output_format>

    where,

    <oputils_server_name_or_ip> refers to the dns name or the IP Address of the computer where OpUtils is installed

    <port_number> refers to the port at which the OpUtils is being run, the default being 7080

    <api_version> refers to the version of the OpUtils API. The current version is 1

    <oputils_module> refers to the OpUtils module which you are querying to get the information. Refer to the Supported OpUtils Modules for which API is currently supported

    <api_key> refers to the API Key for authenticating the query. The API Key is unique for every OpUtils User and has to be generated as per the instructions provided here.

    <operation_name> refers to the API Operation that you use for getting the information. The Operation Name varies for different type of data that you require and for different OpUtils modules. Refer to module specific document for supported operations and operation parameters.

    <operation_parameters> refers to the parameters or arguments for the parameter. Not all operations require a parameter; refer to module specific document for supported operations and operation parameters.

    <output_format> refers to the format at which the results are returned. Refer to Supported Output Formats for details on supported output formats.

    Example:
    http://oputils-test1:7080/oputilsapi/ipam?v=1&key=27559d9f-9866-411e-a71b-c44c2a04f299&operation=GET_SUBNET_SUMMARY&subnetAddress=192.168.118.0&format=xml

    Generating API Key

    API Key validates and authenticates an API request to an OpUtils user so that invalid requests are not entertained. API Key is unique to every OpUtils user and you are allowed to use the API keys of multiple OpUtils users simultaneously.

    To generate an API Key, follow the steps below:

    1. Select Admin --> User Management from OpUtils Web console. This will list the details of all users of OpUtils.
    2. Click the Generate API Key icon  available under the Actions column that corresponds to a user. This opens an Generate API Key dialog where you can either specify an expiry date for this key or choose never to expire.
    3. Click Generate API Key to generate the key. The API key is generated and displayed in the same dialog; you would need to copy and save it separately for using it in your API queries.

    Note: You can regenerate an API key for the users at anytime. However, regenerating an API key invalidates all the previous keys generated for that user.

    HTTP Methods:

    OpUtils API uses appropriate HTTP verbs for every action.

    Method Description:

    • GET Used for retrieving resources.
    • POST Used for creating resources and performing resource actions.
    • PUT Used for updating resources.
    • DELETE Used for deleting resources.

    Supported Output Formats/Response

    The output of an API query will be in JSON format.
    JSON RESPONSE PARAMETERS:

    • code - NetFlow Analyzer error code. Indicates zero for a success response and non-zero in case of an error.
    • message - Status Message for the invoked API.
    • data - Comprising the invoked API’s Data.

    Supported OpUtils Modules

    OpUtils API currently supports the following modules to get the data:

    • IP Address Manager - You should use the module name as 'ipam' in your URL for IP Address Manager module.

    IP Address Manager

    IPAM module will help you get the following information about your IP space from OpUtils database:

    • Subnet Summary: Get the summary information about your subnets like Subnet Name, Subnet Address, Subnet Mask, Subnet Size, Used and Available IP Addresses, etc.
    • IP Address Details:Get the complete details of each and every IP in your network like IP address, MAC Address, IP Status, DNS Status, Reserved Status, Connected Device Type, Authenticity, etc.
    • Subnet Summary: Get the complete details of all the subnets that are discovered in the network, which includes the details on the IP address in each and every subnet.
    • IPAM Alerts:Get alerts on IPAM when specific IP address is used or when the IP address is available.
    • IPAM Alerts:Get the history of the IP allocations and usage, track the changes made IP Address, and get specific details like logged on users, time of logon, date etc for audit purpose.

    IPAM module will help you get the following information about your IP space from OpUtils database:

    • Add Domain: Provides you the ability to add a domain to your network.
    • Add Subnet: Provides you the ability to add a subnet to your network.

    Operations

    The following operations will help you get the required information about your IP space:

    API Name Description Query Params URL
    getInventoryTotalCounts Get the total count of IP Addresses.
    Param Name Description
    apiKey Api Key as string
    GET /api/json/ipam/getInventoryTotalCounts?apiKey=<api_key>

    Request Example http://localhost/api/json/ipam/getInventoryTotalCounts?apiKey=f6f17c2e26cceb01e1020ce68cade2cf
    getAllAddresses Get the list of all IP Addresses
    Param Name Description
    apiKey Api Key as string
    rows Specify the no of IP Addresses you want to fetch Warning : Higher count consumes high CPU and runvtime memory
    page Specify the range of rows that you want to fetch (eg. if you specify 2 it will fetch rows 101 to 200 where considering rows=100) *The Api Response will list the total no of pages, total count
    GET /api/json/ipam/getAllAddresses?apiKey=<api_key>

    Request Example http://localhost/api/json/ipam/getAllAddresses?apiKey=f6f17c2e26cceb01e1020ce68cade2cf&rows=100&page=1
    getUnUsedIP Get details on specific IP address such as if it is used or not.
    Param Name Description
    apiKey Api Key as string
    status Status of the IP Address Supported formats:- Transient = 2 Available = 3
    subnetAddress (Optional) If you want to see the available ips in a particular subnet Warning : Avoiding this param in case of higher count of Unused IP Addresses consumes high CPU and runtime memory.
    GET /api/json/ipam/getUnUsedIP?apiKey=<api_key>&status=3

    Request Example http://localhost/api/json/ipam/getUnUsedIP?apiKey=f6f17c2e26cceb01e1020ce68cade2cf&status=3&subnetAddress=172.21.197.0
    (or)
    http://localhost/api/json/ipam/getUnUsedIP?apiKey=f6f17c2e26cceb01e1020ce68cade2cf&status=2&subnetAddress=172.21.197.0
    updateIPState Update the the state of IP addresses as used, available, transient, reserved, or unreserved.
    Param Name Description
    apiKey Api Key as string
    markAs Specify the State of the IP Address as String Supported formats:-markAs=Reserved/UnReserved/Available/Transient/Used
    IPADDRESS Specify the IP Address as String, Comma separated value.
    RESOURCEID (Optional) Specify the resourceid of the IP Address
    POST /api/json/ipam/updateIPState?apiKey=<api_key>&markAs=<ip_state>

    Request Example http://localhost/api/json/ipam/updateIPState?apiKey=b9769436558edae405466cbc84e0acfc&markAs=Reserved&IPADDRESS=192.168.23.178
    (or)
    http://localhost/api/json/ipam/updateIPState?apiKey=b9769436558edae405466cbc84e0acfc&markAs=Used&IPADDRESS=192.168.23.178, 192.168.23.179
    getAllSubnetSummary Provides the summary details of all the subnets in your network. This operation does not require any additional parameter.
    Param Name Description
    apiKey Api Key as string
    rows Specify the no of IP Addresses you want to fetch Warning : Higher count consumes high CPU and run time memory.
    page Specify the IP Address as String, Comma separated value. 
    GET api/json/ipam/getAllSubnetSummary?apiKey=<api_key>&&rows=100&page=1

    Request Example http://172.21.153.153:8060/api/json/ipam/getAllSubnetSummary?apiKey=df2eac29ef194f4e5e412d36d6899611&&rows=100&page=1
    getSubnetSummary Provides you the summary details of a specified subnet. You would need to specify the Subnet address as a parameter for this operation.
    Param Name Description
    apiKey Api Key as string
    subnetAddress Specify the Subnet Address you want to fetch
    snapType Specify as IPAMSubnet
    GET api/json/ipam/getSubnetSummary?subnetAddress=172.21.10.0&apiKey=df2eac29ef194f4e5e412d36d6899611&snapType=IPAMSubnet

    Request Example http://172.21.153.153:8060/api/json/ipam/getSubnetSummary?subnetAddress=172.21.10.0&apiKey=df2eac29ef194f4e5e412d36
    getSubnetDetail Provides the complete details of all the IP Addresses in the specified subnet
    Param Name Description
    apiKey Api Key as string
    subnetAddress Specify the Subnet Address you want to fetch
    GET api/json/ipam/getSubnetDetails?subnetAddress=172.21.10.0&apiKey=df2eac29ef194f4e5e412d36d6899611

    Request Example http://172.21.153.153:8060/api/json/ipam/getSubnetDetails?subnetAddress=172.21.10.0&apiKey=df2eac29ef194f4e5e412d36d6899611
    getAllSubnetSummary Provides the details of all the subnets discovered in your network
    Param Name Description
    apiKey Api Key as string
    rows Specify the no of IP Addresses you want to fetch
    Warning : Higher count consumes high CPU and run time memory.
    byGroup byGroup value is 1 for discovered subnet
    page Specify the IP Address as String, Comma separated value.
    GET api/json/ipam/getAllSubnetSummary?apiKey= &&rows=100&page=1

    Request Example http://172.21.153.153:8060/api/json/ipam/getAllSubnetSummary?apiKey=df2eac29ef194f4e5e412d36d6899611&&rows=100&page=1&subfilter=byGroup&byGroup=1
    getAllIPAMAlerts Provides the details on all IPAM alerts
    Param Name Description
    apiKey Api Key as string
    GET /api/json/ipam/getInventoryTotalCounts?apiKey=<api_key>

    Request Example http://localhost/api/json/ipam/getInventoryTotalCounts?apiKey=f6f17c2e26cceb01e1020ce68cade2cf
    getIPAMAlerts Provides the details on specific subnet alerts.
    Param Name Description
    apiKey Api Key as string
    subnetAddress Specify the Subnet Address you want to fetch
    GET /api/json/ipam/getIPAMAlerts?apiKey=<api_key>

    Request Example http://localhost/api/json/ipam/getIPAMAlerts?apiKey=f6f17c2e26cceb01e1020ce68cade2cf&subnetAddress=172.21.10.0
    getAllIPAMHistory Provides the details on all IPAM history.
    Param Name Description
    apiKey Api Key as string
    GET /api/json/ipam/getInventoryTotalCounts?apiKey=<api_key>

    Request Example http://localhost/api/json/ipam/getInventoryTotalCounts?apiKey=f6f17c2e26cceb01e1020ce68cade2cf
    getIPAMHistory Provides the details on specific subnet history.
    Param Name Description
    apiKey Api Key as string
    subnetAddress Specify the Subnet Address you want to fetch
    GET /api/json/ipam/getIPAMHistory?apiKey=<api_key>

    Request Example http://localhost/api/json/ipam/getIPAMHistory?apiKey=f6f17c2e26cceb01e1020ce68cade2cf&subnetAddress=172.21.10.0
    getUnUsedIP Provides details on all unused IP address
    Param Name Description
    apiKey Api Key as string
    GET /api/json/ipam/getUnUsedIP?apiKey=<api_key>

    Request Example http://localhost/api/json/ipam/getUnUsedIP?apiKey=f6f1
    getReservedIP Provides details on All Reserved IP address
    Param Name Description
    apiKey Api Key as string
    GET /api/json/ipam/getReservedIP?apiKey=<api_key>

    Request Example http://localhost/api/json/ipam/getReservedIP?apiKey=f6f17c2e26cceb01e1020ce68cade2cf
    getReservedIP To get details on specific IP address
    Param Name Description
    apiKey Api Key as string
    subnetAddress Specify the Subnet Address you want to fetch
    GET /api/json/ipam/getReservedIP?apiKey=<api_key>

    Request Example http://localhost/api/json/ipam/getReservedIP?apiKey=f6f17c2e26cceb01e1020ce68cade2cf&subnetAddress=172.21.10.0
    getOpUtilsAudit Provides all details on the IPAM for audit
    Param Name Description
    apiKey Api Key as string
    tool Give value is "IP_ADDRESS_MANAGER"
    GET /api/json/oputilsreports/getOpUtilsAudit?apiKey=<api_key>& subnetAddress

    Request Example http://localhost/api/json/oputilsreports/getOpUtilsAudit?apiKey=f6f17c2e26cceb01e1020ce68cade2
    addSubnet To add details of a subnet
    Param Name Description
    apiKey Api Key as string
    subnetAddress Specify the Subnet Address you want to add
    subnetMask Specify the Subnet Mask
    addType subnet add type
    POST api/json/ipam/addSubnet?subnetAddress=172.21.10.0&subnetMask=255.255.255.0&addType=manual&apiKey=api key

    Request Example http://172.21.153.153:8060/api/json/ipam/addSubnet?subnetAddress=172.21.10.0&subnetMask=255.255.255.0&addType=manual&apiKey=df2eac29ef194f4e5e412d36d6
    addDomain To add domain details of a domain
    Param Name Description
    apiKey Api Key as string
    userName User Name
    password Password
    domainName Domain Name
    domainController Domain Controller
    POST api/json/admin/addDomain?apiKey=<api_key>&domainName=<domainName>&controllerName=<domainController>&userName=<userName>&password=<password>

    Request Example http://172.21.153.153:8060/api/json/admin/addDomain?apiKey=df2eac29ef194f4e5e412d36d6899611&domainName=zohocorp&controllerName=opu-w7-11&userName=admin&password=zoho
    deleteSubnets To delete a subnet
    Param Name Description
    apiKey Api Key as string
    subnetAddress Specify the Subnet Address you want to add
    POST api/json/ipam/deleteSubnets?subnetAddress=192.168.22.0&apiKey=api Key

    Request Example http://172.21.153.153:8060/api/json/ipam/deleteSubnets?subnetAddress=192.168.22.0&apiKey=df2eac29ef194f4e5e412d36d6
    updateIPAMSettings update IP Address manager Settings (Add DNS Server)
    Param Name Description
    apiKey Api Key as string
    isShowMac (on/off)to remember the MAC Address and device details to which the IP was assigned previously till it get assigned to a different device.
    dnsServer Specify the DNS Server to be used for resolving the DNS Names of the IP Addresses.(comma seperated for multiple dns server)
    isEnabledStackPort (true/false)To display switch port details of all the MACs learned with a switch port and all the switch ports learned by a MAC.
    POST api/json/oputilsadmin/updateIPAMSettings?isShowMac=on&dnsServer=cse.example.com,mydomain.com&isEnabledStackPort=false&apiKey=api key

    Request Example http://172.21.153.153:8060/api/json/oputilsadmin/updateIPAMSettings?isShowMac=on&dnsServer=cse.example.com,mydomain.com&isEnabledStackPort=false&apiKey=df2eac29ef194f4e5e412d36d6
    getIPAMSettings to get update IP Address Manager Settings(DNS Server Addedx)
    Param Name Description
    apiKey Api Key as string
    subnetAddress Specify the Subnet Address you want to add
    GET api/json/oputilsadmin/getIPAMSettings?apiKey=api key

    Request Example http://172.21.153.153:8060/api/json/oputilsadmin/getIPAMSettings?apiKey=df2eac29ef194f4e5e412d36d6
    getUnUsedIP Get details on specific IP address such as if it is used or not.
    Param Name Description
    rows (50/100/500)Specify the no of IP Addresses you want to fetch Warning : Higher count consumes high CPU and runvtime memory
    page Specify the range of rows that you want to fetch (eg. if you specify 2 it will fetch rows 101 to 200 where considering rows=100) *The Api Response will list the total no of pages, total count
    status Status of the IP Address Supported formats:- Transient = 2 Available = 3 Used = 1 All IPs = All
    GET api/json/ipam/getUnUsedIP?rows=100&status=3&page=1&apiKey=api key

    Request Example http://172.21.153.153:8060/api/json/ipam/getUnUsedIP?rows=100&status=3&page=1&apiKey=df2eac29ef194f4e5e412d36d6
    api/json/oputilsadmin/addIPAMCustomColumn To Add custom columns
    Param Name Description
    apiKey Api Key as string
    dataType dataType of column created(INTEGER,2STRING,1 BOOLEAN,3)
    size size of column elements
    defaultValue default value for column
    desc Description about column
    tableName type of custom column (SubnetLevelCustomField,SPMSwitchLevelCustomField,IPAMIPLevelCustomField,SPMPortLevelCustomField)
    tableID ID of custom column Table(2->Subnet,
    1->IP,
    3->Port,
    4->Switch)
    POST api/json/oputilsadmin/addIPAMCustomColumn?dataType=STRING,1&columnName=TestSubnet&size=50&defaultValue=E01&desc=Description&tableName=SubnetLevelCustomField&tableID=2

    Request Example http://172.21.153.153:8060/api/json/oputilsadmin/addIPAMCustomColumn?dataType=STRING,1&columnName=TestSubnet&size=50&defaultValue=E01&desc=Description&tableName=SubnetLevelCustomField&tableID=2&apiKey=df2eac29ef194f4e5e412d36d6

    Switch Port Mapper

    Switch Port Mapper module APIs will help you get the following information about your monitored switch ports from OpUtils database:

    • Switch summary: Get the summary information of a specific switch are of all monitored switches added to your OpUtils console.
    • Switch port details:Get the complete details of specific or all switch ports in your network.
    • Switch history: View the port utilization history logged over time by OpUtils. You can get the history of all or specific switch ports.
    • Switch port mapper alerts: Get switch port specific alerts triggered by the Switch Port Mapper module.
    • Adding a switch port:Add a particular switch port to be monitored, manually to the OpUtils console using the specified switch port mapper API.

    Operations

    The following operations will help you get the required information about your switch ports:

    API Name Description Query Params URL
    getSwitchSummary Get the switch summary details of a particular switch
    Param Name Description
    apiKey API key as string
    GET getAllSwitchesSummary

    Request Example http://localhost:8060/client/API/json/spm/getAllSwitchesSummary
    getSwitchSummary Get the switch summary details of a particular switch.
    Param Name Description
    apiKey Specify the Switch IP / DNS
    E.g. switchIP=192.168.90.4
    switchIP API Key as string
    GET getSwitchSummary

    Request Example http://localhost:8060/client/API/json/spm/getSwitchSummary?switchIP=192.168.90.4
    getPortDetails Get a particular switch port's details
    Param Name Description
    apiKey API Key as string
    switchIP Specify the Switch IP / DNS E.g. switchIP=192.168.90.4
    GET getPortDetails

    Request Example http://localhost:8060/client/API/json/spm/getPortDetails?switchIP=192.168.90.4
    getAllPortHistory Get the history of all monitored switches
    Param Name Description
    apiKey API Key as string
    GET getAllPortHistory

    Request Example http://localhost:8060/client/API/json/spm/getSPMAlerts?switchIP=192.168.90.4
    getAllSPMAlerts Get the history of all monitored switches
    Param Name Description
    apiKey API Key as string
    GET getAllSPMAlerts

    Request Example http://localhost:8060/client/API/json/spm/getAllSPMAlerts
    addSwitch Add a switch to OpUtils
    Param Name Description
    apiKey API Key as string
    switchIP Specify the Switch IP / DNS E.g. switchIP=192.168.90.4
    addType Set as "manual"
    parentID=2 2 is default tree group
    credentialNames=Public Specify the snmp credential name
    arpDetails=true or false Enable or disable of collecting ARP details from switch
    sysDetails=true or false Enable or disable of collecting sys details from switch
    snmpPingSweepEnable=true or false Enable or disable for do ping sweep
    GET addSwitch

    Request Example http://localhost:8060/client/API/json/spm/addSwitch?switchIP=192.168.10.10&addType=manual&parentID=2&credentialNames=Public&arpDetails=true&sysDetails=true&snmpPi