Chapter 1. Overview

Information About the Cisco Nexus 1000V REST API

Finding Supported Resource Names

List of Available Resource Names for the Cisco Nexus 1000V

Chapter 2. Cisco Nexus 1000V API Functions

Get Information About the Uplink Ports Configured on the VSM

Get the Cisco Nexus 1000V Licensing Status

Get a List of Port Profiles Configured on the VSM

Get Information About the Virtual Ethernet Ports Connected to the Cisco Nexus 1000V Switch

Get a Summary of the Cisco Nexus 1000V Switch

Preface

Audience

Document Conventions

Related Documentation for Cisco Nexus 1000V for KVM Software

Documentation Feedback

Obtaining Documentation and Submitting a Service Request

Copyright Page

Chapter 1. Overview

This chapter contains the following sections:

- Information About the Cisco Nexus 1000V REST API

- Finding Supported Resource Names

- List of Available Resource Names for the Cisco Nexus 1000V

Information About the Cisco Nexus 1000V REST API

The REST API 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/n1k/license

n1k 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/n1k/license

The browser prompts you for a username and a password and returns the HTML output.

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

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

You get the following XML output:

<set name="license_set">
<instance name="NEXUS_VSG_SERVICES_PKG" url="/api/n1k/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/n1k/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/n1k/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>

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/n1k

You get the following output:

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

List of Available Resource Names for the Cisco Nexus 1000V

Available Resource Names

Namespace

Description

/api/n1k

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

/api/n1k/uplink

Lists the details of the uplink interfaces configured on the VSM.

/api/n1k/vnic

Lists the details of the virtual Ethernet ports connected to the Nexus 1000V switch.

/api/n1k/port-profile

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

/api/n1k/summary

Lists a summary of the Cisco Nexus 1000V switch.

/api/n1k/license

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

Chapter 2. Cisco Nexus 1000V API Functions

This chapter provides information about the Cisco Nexus 1000V application programming interface (API) functions. The Cisco Nexus 1000V resource name is generic across all hypervisors. The functions that support write (create, update, and delete) operations are explicitly marked as writeable. All others are read-only functions.

The chapter contains the following topics:

- Get Information About the Uplink Ports Configured on the VSM

- Get the Cisco Nexus 1000V Licensing Status

- Get a List of Port Profiles Configured on the VSM

- Get Information About the Virtual Ethernet Ports Connected to the Cisco Nexus 1000V Switch

- Get a Summary of the Cisco Nexus 1000V Switch

Get Information About the Uplink Ports Configured on the VSM

Object Locator

["/api/n1k/uplink"] [Read-only]

Description

Retrieves information about the uplink ports configured on the VSM.

Response Sample

<set name="uplink_set">
<instance name="Ethernet5/2" url="/api/n1k/uplink/Ethernet5%2F2">
<properties>
<module>5</module>
<packetsTx>3801</packetsTx>
<mtu>1500</mtu>
<cdpPort>Ethernet101/1/5</cdpPort>
<cdpSwitch>sf-n5k-14(SSI134306N1)</cdpSwitch>
<cdpNativeVlan>231</cdpNativeVlan>
<packetsRx>16114898</packetsRx>
<vlans>250-350</vlans>
<name>Ethernet5/2</name>
<ethernet>Ethernet</ethernet>
<speed>1000 Mb/s</speed>
<mode>trunk</mode>
<portProfile>sys-uplink</portProfile>
<status>up</status>
</properties>
</instance>
</set>

Response Description

Property

Writeable or Readable

module

Readable

portChannelType

Readable

packetsTx

Readable

mtu

Readable

cdpPort

Readable

port

Readable

status

Readable

mode

Readable

vlans

Readable

portChannel

Readable

cdpNativeVlan

Readable

portChannelMembers

Readable

packetsRx

Readable

cdpswitch

Readable

portProfile

Readable

speed

Readable

Get the Cisco Nexus 1000V Licensing Status

Object Locator

["/api/n1k/license"] [Read-only]

Description

Retrieves information about the licensing details of the Cisco Nexus 1000V switch.

Response Sample

<set name="license_set">
<instance name="NEXUS1000V_LAN_SERVICES_PKG"
url="/api/n1k/license/NEXUS1000V_LAN_SERVICES_PKG">
<properties>
<expires>N/A</expires>
<type>NEXUS1000V_LAN_SERVICES_PKG</type>
<available>0</available>
<status>Unused</status>
<used>0</used>
</properties>
</instance>
</set>

Response Description

Property

Writeable or Readable

expires

Readable

type

Readable

available

Readable

status

Readable

used

Readable

Get a List of Port Profiles Configured on the VSM

Object Locator

["/api/n1k/port-profile"] [Read-only]

Description

Retrieves a list of all of the port profiles that are configured on the VSM.

Response Sample

<set name="portProfile_set">
<instance name="policy-1" url="/api/n1k/port-profile/policy-1">
<properties>
<maxPorts>32</maxPorts>
<type>Vethernet</type>
<name>policy-1</name>
<systemVlans>none</systemVlans>
<status>1</status>
<minPorts>1</minPorts>
<vlans></vlans>
<usedPorts>0</usedPorts>
</properties>
</instance>
</set>

Response Description

Property

Writeable or Readable

maxPorts

Readable

type

Readable

systemVlans

Readable

status

Readable

minPorts

Readable

vlans

Readable

usedPorts

Readable

Get Information About the Virtual Ethernet Ports Connected to the Cisco Nexus 1000V Switch

Object Locator

["/api/n1k/vnic"] [Read-only]

Description

Retrieves information about the virtual Ethernet ports that are connected to the Cisco Nexus 1000V switch.

Response Sample

<set name="vnic_set">
<instance name="Vethernet5" uri="/api/vc/vnic/Vethernet5">
<properties>
<mac>0050.56ba.58bc</mac>
<dvport>DVPort65</dvport>
<adapter>Net Adapter 1</adapter>
<hostIP>172.23.231.192</hostIP>
<vlans>231</vlans>
<portGroup>n1kv-system-control</portGroup>
<status>up</status>
<module>3</module>
<vm>vsm-vcplugin-1-2</vm>
<vnic>Vethernet5</vnic>
</properties>
</instance>
</set>

Response Description

Property

Writeable or Readable

mac

Readable

dvport

Readable

adapter

Readable

vlans

Readable

portGroup

Readable

status

Readable

module

Readable

vm

Readable

vnic

Readable

Get a Summary of the Cisco Nexus 1000V Switch

Object Locator

["/api/n1k/summary"] [Read-only]

Description

Retrieves a summary of the Cisco Nexus 1000V switch.

Response Sample

<set name="summary_set">
<instance url="/api/n1k/summary">
<properties>
<haStatus>false</haStatus>
<name>switch</name>
<switchMode>ESSENTIAL</switchMode>
<mode>L3</mode>
<version>version 5.2(1)SK1(2.1)
[gdb]</version>
<ip>172.23.231.45</ip>
</properties>
</instance>
</set>

Response Description

Property

Writeable or Readable

haStatus

Readable

name

Readable

switchMode

Readable

mode

Readable

version

Readable

ip

Readable

Preface

This preface contains the following sections:

- Audience

- Document Conventions

- Related Documentation for Cisco Nexus 1000V for KVM Software

- Documentation Feedback

- Obtaining Documentation and Submitting a Service Request

Audience

This publication is for network administrators who configure and maintain Cisco Nexus devices.

This guide is for network and server administrators with the following experience and knowledge:

- An understanding of virtualization

- An understanding of the corresponding hypervisor management software for your switch, such as VMware vSwitch, Microsoft System Center Virtual Machine Manager (SCVMM), or OpenStack.

Document Conventions

Command descriptions use the following conventions:

Convention

Description

bold

Bold text indicates the commands and keywords that you enter literally as shown.

Italic

Italic text indicates arguments for which the user supplies the values.

[x]

Square brackets enclose an optional element (keyword or argument).

[x | y]

Square brackets enclosing keywords or arguments separated by a vertical bar indicate an optional choice.

{x | y}

Braces enclosing keywords or arguments separated by a vertical bar indicate a required choice.

[x {y | z}]

Nested set of square brackets or braces indicate optional or required choices within optional or required elements. Braces and a vertical bar within square brackets indicate a required choice within an optional element.

variable

Indicates a variable for which you supply values, in context where italics cannot be used.

string

A nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks.

Examples use the following conventions:

Convention

Description

screen font

Terminal sessions and information the switch displays are in screen font.

boldface screen font

Information you must enter is in boldface screen font.

italic screen font

Arguments for which you supply values are in italic screen font.

< >

Nonprinting characters, such as passwords, are in angle brackets.

[ ]

Default responses to system prompts are in square brackets.

!, #

An exclamation point (!) or a pound sign (#) at the beginning of a line of code indicates a comment line.

This document uses the following conventions:

Note

Means reader take note. Notes contain helpful suggestions or references to material not covered in the manual.

Caution

Means reader be careful. In this situation, you might do something that could result in equipment damage or loss of data.

Related Documentation for Cisco Nexus 1000V for KVM Software

This section lists the documents used with the Cisco Nexus 1000V for KVM software:

General Information

Cisco Nexus 1000V for KVM Release Notes

Install and Upgrade

Cisco Nexus 1000V for KVM Software Installation Guide

Configuration Guides

Cisco Nexus 1000V for KVM High-Availability Configuration Guide

Cisco Nexus 1000V for KVM Interface Configuration Guide

Cisco Nexus 1000V for KVM Layer 2 Configuration Guide

Cisco Nexus 1000V for KVM License Configuration Guide

Cisco Nexus 1000V for KVM Virtual Network Configuration Guide

Cisco Nexus 1000V for KVM Port Profile Configuration Guide

Cisco Nexus 1000V for KVM REST API Configuration Guide

Cisco Nexus 1000V for KVM Security Configuration Guide

Cisco Nexus 1000V for KVM System Management Configuration Guide

Cisco Nexus 1000V for KVM Verified Scalability Guide

Cisco Nexus 1000V for KVM VXLAN Configuration Guide

Reference Guides

Cisco Nexus 1000V for KVM Command Reference

Cisco Nexus 1000V for KVM OpenStack REST API Reference

Troubleshooting and Alerts

Cisco Nexus 1000V for KVM Troubleshooting Guide

Documentation Feedback

To provide technical feedback on this document, or to report an error or omission, please send your comments to:

- nexus1k-docfeedback@cisco.com

We appreciate your feedback.

Obtaining Documentation and Submitting a Service Request

For information on obtaining documentation, using the Cisco Bug Search Tool (BST), submitting a service request, and gathering additional information, see What's New in Cisco Product Documentation, at: Click Here .

Subscribe to What's New in Cisco Product Documentation, which lists all new and revised Cisco technical documentation, as an RSS feed and deliver content directly to your desktop using a reader application. The RSS feeds are a free service.

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: Click Here . Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R)