Cisco Nexus 1000V REST API Plug-in Configuration Guide, Release 4.2(1)SV2(2.1)
Overview
Downloads: This chapterpdf (PDF - 1.09MB) The complete bookPDF (PDF - 2.02MB) | The complete bookePub (ePub - 159.0KB) | Feedback

Overview

Overview

This chapter contains the following sections:

Information About the Cisco Nexus 1000V REST API Plug-in

Starting with Cisco Nexus 1000V Release 4.2(1)SV2(2.1), an extensible plug-in architecture is supported on the Cisco Nexus 1000V. The REST API plug-in supports retrieving system information from the Cisco Nexus 1000V.

You can read an object on the Cisco Nexus 1000V Virtual Supervisor Module (VSM) using the Representational State Transfer (REST) web services API. In order to call any REST function, you can use tools such as a web browser, the cURL tool, and Windows PowerShell.

The following is the basic construct of a REST URL:

http[s]://<IP_address>/api/<resource locator>

The resource locator consists of two parts:

<resource locator> := <name space>/<resource name>

<name space> indicates the broader class of functions and <resource name> refers to the specific object.

For example, in the following URL:

http://10.10.10.2/api/vc/license

vc is the namespace and license is the resource name.

If you are using a browser, type in the URL. For example, if you want to get the license information of your VSM that has an IP address of 10.10.10.2, you type the URL as follows:

https://10.10.10.2/api/vc/license

The browser prompts you for a username and a password. After entering them, you get the following output:

<set name="license_set">
<instance name="NEXUS_VSG_SERVICES_PKG" url="/api/vc/license">
<properties>
<expires>04 May 2013</expires>
<type>NEXUS_VSG_SERVICES_PKG</type>
<available>512</available>
<status>Unused</status>
<used>0</used>
</properties>
</instance>
<instance name="NEXUS_ASA1000V_SERVICES_PKG" url="/api/vc/license">
<properties>
<expires>04 May 2013</expires>
<type>NEXUS_ASA1000V_SERVICES_PKG</type>
<available>16</available>
<status>Unused</status>
<used>0</used>
</properties>
</instance>
<instance name="NEXUS1000V_LAN_SERVICES_PKG" url="/api/vc/license">
<properties>
<expires>04 May 2013</expires>
<type>NEXUS1000V_LAN_SERVICES_PKG</type>
<available>1024</available>
<status>Unused</status>
<used>0</used>
</properties>
</instance>
</set>

To access the same through cURL, you use the following format:

curl http://username:password@10.10.10.2/api/vc/license

Finding Supported Resource Names

Every REST API function is associated with a resource name

To find the list of Cisco Nexus 1000V resource names, construct the URL as follows:

https://10.10.10.2/api/vc

You get the following output:

<set name="api_set">
<instance url="/api/vc">
<children>
<child name="uplink" url="/api/vc/uplink"/>
<child name="limits" url="/api/vc/limits"/>
<child name="vnic" url="/api/vc/vnic"/>
<child name="port-profile" url="/api/vc/port-profile"/>
<child name="vem" url="/api/vc/vem"/>
<child name="summary" url="/api/vc/summary"/>
<child name="license" url="/api/vc/license"/>
</children>
</instance>
</set>

List of Available Resource Names for the Cisco Nexus 1000V

Table 1 Available Resource Names

Namespace

Description

/api/vc

Lists the seven available elements that can be queried through the interface.

/api/vc/uplink

Lists the details of the uplinks configured on the VSM.

/api/vc/limits

Lists the resource availability on the Cisco Nexus 1000V switch.

/api/vc/vnic

Lists the details of the virtual Ethernet ports connected to the switch.

/api/vc/port-profile

Lists the details of the port profiles configured on the VSM.

/api/vc/vem

Lists the details of the Virtual Ethernet Modules (VEMs) attached on the VSM.

/api/vc/summary

Lists a summary of the Cisco Nexus 1000V switch.

/api/vc/license

Lists the licensing status of the Cisco Nexus 1000V switch.

REST API Architecture

Starting with Cisco Nexus 1000V Release 4.2(1)SV2(2.1), an extensible plug-in architecture is supported on the Cisco Nexus 1000V. Additional REST APIs can be installed using this plug-in infrastructure to expand the capabilities of the API and retrieve a broader set of information from the switch.

See the following figure for the supported architecture on the Cisco Nexus 1000V switch. In the figure, the VMware Virtual Channel (VC) is an example of the REST API caller.
Figure 1. REST API Architecture



Guidelines and Limitations

  • Before you load the REST API plug-in, the plug-in must be available in the bootflash of the active and standby directory.
  • Ensure that you unload the REST API plug-in that is installed during boot time before loading the REST API plug-in from the bootflash.
  • You cannot install multiple plug-ins on the same system.
  • The REST API plug-in load and unload commands are supported only in the VSM HA mode.
  • Ensure that you do not switch over or reload the VSM immediately after unloading the REST API plug-in.