Getting Started

The following sections introduce you to NFVIS API and provide information on how to use the API.

Base URL

Every API request begins with the following base URL.

https://{nfvis_host_ip}/restconf/

What are NFVIS API used for?

NFVIS API enables you to automate network functions and infrastructure operations on the NFVIS platform. The set includes API related to the following:

System and IP Configuration: Configure and manage system settings and IP addresses for your NFVIS environment.
PnPs (Plug and Play): Facilitate the plug-and-play bootstrapping and configuration of devices that are connected to the NFVIS platform.
Resources: Manage the allocation and monitoring of hardware resources like CPU, memory, and storage for virtual machines.
Networks and Bridges: Configure and manage virtual networks and bridge connections, enabling effective communication between VMs.
VM Lifecycle Management: Handle the creation, modification, deployment, and deletion of virtual machines hosted on NFVIS.
System Monitoring: Provide tools for tracking system performance, health metrics, and resource utilization.
System Operations: Conduct various operational tasks such as system reboots, shutdowns, and maintenance activities.
SPAN Session and Packet Capture: Enable the configuration of SPAN sessions and capture network packets for analysis and troubleshooting.
Upgrade Package: Manage software upgrades and updates for the NFVIS platform and its components.
Factory Default Reset: Reset the NFVIS system to its factory default settings, erasing all custom configurations.
Syslog Support: Configure and manage syslog settings for logging system events and alerts.
SNMP Support: Configure SNMP settings, enabling network management and monitoring through SNMP protocols.
TACACS and RADIUS Support: Configure authentication, authorization, and accounting services using TACACS+ and RADIUS protocols.
Port and Port Channel: Manage physical and virtual ports, including port channel configurations for link aggregation.
Port Security: Provide security measures and configurations for protecting network ports from unauthorized access.
Secure Overlay: Configure secure overlay networks, enhancing security and connectivity between distributed network elements.
BGP Support: Enable the configuration and management of BGP routing protocols within the NFVIS environment.

Content Types

The payload in the request can use XML or JSON format, and you need to set the headers (Content-Type and Accept) accordingly.

The system supports the following two groups of headers:

Header	Description
XML	Content-Type: application/yang-data+xml For collection results: application/vnd.yang.collection+xml Accept: application/yang-data+xml
JSON	Content-Type: application/yang-data+json Accept:application/yang-data+json

API Request Methods

The following are the supported NFVIS API request methods:

HTTP Request Method	Description
GET	Retrieves the specified resource or representation. GET is Read-only operation that does not change the engine state or have any side effects. >Note: The GET method supports ?content=config to get the config details only, ?content=nonconfig get the operational details only and ?content=all query to get both config and operational information.
POST	Submits data for processing to the specified resource, including the data in the request body. A POST operation can create a new resource.
PUT	Updates the specified resource with new information. The data included in the PUT operation replaces the previous data. * The PUT operation replaces or modifies an existing resource. You cannot use the PUT operation to create a new resource. * The request body of a PUT operation must contain the complete representation of the mandatory attributes of the resource.
DELETE	Deletes a resource. If you delete a resource already deleted, the system returns a 404 Not Found response.

Note: You can use any command-line tool, such as cURL, that supports transferring of data using the HTTPS protocol. You need to precede all NFVIS API commands with https://nfvis_host_ip. This is the Cisco Enterprise NFVIS host IP address.

Example 1. A RESTCONF request using cURL

# The command appears over several lines to fit.
#
# The switch '-i' will include any HTTP reply headers in the output.
# and the '-s' will suppress some superfluous output.
#
# The '-u' switch specify the User: Password for login authentication.
#
# The '-H' switch adds an HTTP header to the request; in this case.
# Add an 'Accept' header to request the preferred reply format.
#
# Finally, the complete URL to the wanted resource is specified,
# in this case the top of the configuration tree.
#

$ curl -is -u admin:admin \
    -H "Accept: application/yang-data+xml" \
    "https://a.b.c.d/restconf/data/"

In the rest of the document, to simplify the presentation, the preceding example will be expressed as:

Example 2. A RESTCONF request, simplified

GET /restconf/data
Accept: application/yang-data+xml

HTTP/1.1 200 OK

Note: The HTTP return code (200 OK) in the example, which appears along with any relevant HTTP headers returned and a possible content body.

Get resources under the data resource

To fetch configuration or operational data from the server, make a request to the data resource. To limit the returned data, the example prunes the output to include only the top nodes using the depth query argument.

Example 3. Get the top most resources under the data

GET /restconf/data?depth=1
Accept: application/yang-data+xml

The server might respond as follows:

<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<rollback-files xmlns="http://tail-f.com/ns/rollback"/>
<yang-library xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"/>
<modules-state xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"/>
<banner-motd xmlns="http://www.cisco.com/nfvis/banner"/>
<bridge-settings xmlns="http://www.cisco.com/nfvis/bridges"/>
<hostaction xmlns="http://www.cisco.com/nfvos/hostaction"/>
<netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring"/>
<restconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"/>
<debug-logs xmlns="http://www.cisco.com/nfv/log"/>
<netsnmp xmlns="http://www.cisco.com/nfvis/netsnmp"/>
<networks xmlns="http://www.cisco.com/nfv/network"/>
<bridges xmlns="http://www.cisco.com/nfv/network"/>
<platform-detail xmlns="http://www.cisco.com/nfvos/platform-info"/>
<pnics xmlns="http://www.cisco.com/nfvis/pnic"/>
<lldp xmlns="http://www.cisco.com/nfvis/pnic"/>
<pnics-detail xmlns="http://www.cisco.com/nfvis/pnic-detail"/>
<pnp xmlns="http://www.cisco.com/nfv/pnp"/>
<rbac xmlns="http://www.cisco.com/nfv/rbac"/>
<resources xmlns="http://www.cisco.com/nfvis/resources"/>
<routers xmlns="http://www.cisco.com/nfvis/router"/>
<security xmlns="http://www.cisco.com/ns/test/security"/>
<security_servers xmlns="http://www.cisco.com/ns/test/security"/>
<bgp xmlns="http://www.cisco.com/nfvis/bgp_status"/>

Manipulating config data with RESTCONF

Let's assume we are interested in the networks resource in our configuration. We can issue an HTTP GET request to retrieve the existing networks.

Example 4. Get the network resource

GET /restconf/data/network:networks

The server might respond as follows:

  HTTP/1.1 200 OK

  <networks xmlns="http://www.cisco.com/nfv/network"  xmlns:network="http://www.cisco.com/nfv/network">
    <network>
        <name>wan-net</name>
        <bridge>wan-br</bridge>
        <exists>true</exists>
    </network>
    <network>
        <name>wan2-net</name>
        <bridge>wan2-br</bridge>
        <exists>true</exists>
    </network>
    <network>
        <name>lan-net</name>
        <bridge>lan-br</bridge>
        <exists>true</exists>
    </network>
    <network>
        <name>GE0-0-SRIOV-1</name>
        <sriov>true</sriov>
        <exists>true</exists>
    </network>
    <network>
        <name>GE0-0-SRIOV-2</name>
        <sriov>true</sriov>
        <exists>true</exists>
    </network>
    <network>
        <name>GE0-1-SRIOV-1</name>
        <sriov>true</sriov>
        <exists>true</exists>
    </network>
    <network>
        <name>GE0-1-SRIOV-2</name>
        <sriov>true</sriov>
        <exists>true</exists>
    </network>
</networks>

Example 5. Create a network

POST /restconf/data/network:networks
Content-Type: application/yang-data+xml
--data
    <network>
        <name>test-net</name>
        <bridge>test-br</bridge>
    </network>

If the resource has been created, the server might respond as follows:

HTTP/1.1 201 Created

Note: The HTTP return code (201 Created), indicating that the system successfully created the resource.

If we now want to modify a network, we can use HTTP PUT method, as below

Example 6. Modify a network resource

PUT /data/network:networks/network=test-net
Content-Type: application/yang-data+xml
--data
    <network>
        <name>test-net</name>
        <bridge>test-br</bridge>
        <vlan>100</vlan>
    </network>

If our modification is successful, the server might respond as follows:

HTTP/1.1 204 No Content

To delete the network, use the DELETE HTTP method as shown below. Since the operation succeeded and did not return a body, you will receive a 204 No Content return code.

Example 7. Delete a network resource

DELETE /data/network:networks/network=test-net

If our delete request is successful, the server might respond as follows:

HTTP/1.1 204 No Content

Download the NFVIS API JSON file

From the main menu, choose NFVIS API > API Reference > Download OpenAPI Document. The OpenAPI document opens as a JSON file in a new tab. You can download the file to your local system to start using the API.