Chapter 1. New and Changed Information

New and Changed Information for REST API Plug-in Configuration Guide

Chapter 2. Overview

Information About the Cisco Nexus 1000V REST API

REST API Architecture

Web Interface

Listing Supported Resource Names

Guidelines and Limitations

Feature History for Overview

Chapter 3. Using the REST API Plug-in

JSON Format

XML Format

GET Method

POST Method

DELETE Method

/api/n1k

/api/n1k/license

/api/n1k/limits

/api/n1k/port-profile

/api/n1k/summary

/api/n1k/uplink

/api/n1k/vem

/api/n1k/vnic

/api/n1k/span

/api/n1k/user

/api/n1k/vlan

/api/n1k/vff

/api/n1k/vrf

/api/n1k/vnode

/api/n1k/vpath

/api/n1k/vxlan

/api/n1k/vc

Executing CLI via REST

Saving Resource Changes

Increase max-port via REST

Feature History for Using the REST API Plug-in

Chapter 4. Configuring the REST API Plug-in

Configuring the REST API Plug-in

Copyright Page

Chapter 1. New and Changed Information

This chapter contains the following sections:

- New and Changed Information for REST API Plug-in Configuration Guide

New and Changed Information for REST API Plug-in Configuration Guide

This section lists new and changed content in this document by software release.

New and Changed Features for REST API Plug-in Configuration Guide

Feature

Description

Changed in Release

Where Documented

Web Interface

The REST API plug-in provides a Web interface to find the available APIs.

4.2(1)SV2(2.1a)

Web Interface

JSON Response Format

The REST API plug-in supports the JSON format for a response.

4.2(1)SV2(2.1a)

Using the REST API Plug-in

HTTP Formats

The REST API plug-in supports the GET, POST, and DELETE methods.

4.2(1)SV2(2.1a)

Using the REST API Plug-in

Cisco Nexus 1000V REST API Resources

The REST API plug-in supports the /api/port-profile, /api/span, /api/user, /api/vlan, /api/vnode, /api/vpath, and /api/vxlan resources.

4.2(1)SV2(2.1a)

Using the REST API Plug-in

Cisco Nexus 1000V REST API Resources

The REST API plug-in supports the /api/vff resource.

4.2(1)SV2(2.2)

Using the REST API Plug-in

Cisco Nexus 1000V REST API Resources

The REST API plug-in supports all generic api's in /api/n1k namespace.

5.2(1)SV3(1.1)

Using the REST API Plug-in

Cisco Nexus 1000V REST API Resources

The REST API plug-in supports the username and password authentication using TACACS+ or RADIUS server.

5.2(1)SV3(1.3)

Information About the Cisco Nexus 1000V REST API

Chapter 2. Overview

This chapter contains the following sections:

- Information About the Cisco Nexus 1000V REST API

- REST API Architecture

- Web Interface

- Listing Supported Resource Names

- Guidelines and Limitations

- Feature History for Overview

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.

Note

Beginning with Cisco Nexus 1000V Release 5.2(1)SV3(1.3), username and password can be authenticated using TACACS+ or RADIUS servers.

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>

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.
REST API Architecture

Web Interface

The REST API plug-in provides a Web interface to find the available APIs. You can access the Web interface from a browser by using the following URL:

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

For resources under /api, you can access the online documentation by appending ?meta to the resource name as shown in the following example:

http[s]://<ip-addr>/api/port-profile?meta

Listing 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:

<?xml version="1.0" encoding="utf-8"?>
<instance url="/api/n1k">
<children>
<child name="vff" url="/api/n1k/vff"/>
<child name="uplink" url="/api/n1k/uplink"/>
<child name="vnic" url="/api/n1k/vnic"/>
<child name="user" url="/api/n1k/user"/>
<child name="vxlan" url="/api/n1k/vxlan"/>
<child name="vnode" url="/api/n1k/vnode"/>
<child name="span" url="/api/n1k/span"/>
<child name="vpath" url="/api/n1k/vpath"/>
<child name="summary" url="/api/n1k/summary"/>
<child name="license" url="/api/n1k/license"/>
<child name="port-profile" url="/api/n1k/port-profile"/>
<child name="vem" url="/api/n1k/vem"/>
<child name="vlan" url="/api/n1k/vlan"/>
<child name="limits" url="/api/n1k/limits"/>
</children>
</instance>

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.

Note

After unloading the REST API plug-in, wait for at least 10 seconds before loading the new REST API plug-in.

- 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.

Feature History for Overview

Feature

Releases

Feature Information

Support for Web Interface

4.2(1)SV2(2.1a)

This feature was introduced.

Chapter 3. Using the REST API Plug-in

This chapter contains the following sections:

- Executing CLI via REST

- Saving Resource Changes

- Increase max-port via REST

- Feature History for Using the REST API Plug-in

JSON Format

The REST API plug-in supports the JavaScript Object Notation (JSON) format for a response. For JSON response, specify Accept: application/json in the HTTP header as shown in the following example:

GET /api/n1k/summary HTTP/1.1
Host: 10.10.10.2
Accept: application/json
Authorization: Basic YWRtaW46U2Zpc2gxMjM=

To specify the JSON response format through cURL, use the following:

curl -u <user>:<password> <vsm-ip>/api/n1k/port-profile -H "Accept: application/json"

The following example shows the response received in the JSON format:

{
"":{"url":"/api/n1k/summary",
"properties":{"vcStatus":"Connected",
"vcIpaddress":"10.197.132.200",
"switchMode":"ADVANCED (3.0)",
"ip":"10.197.132.213","vcUuid":"e7 4f 03 50 3f ab 39 42-67 c9 dc 40 9f 74 45 91",
"name":"switch",
"datacenterName":"Test-DC",
"haStatus":true,
"mode":"L2",
"version":"version 5.2(1)SV3(1.3) [build 5.2(1)SV3(1.2.100)]",
"connectionName":"vc"
}
}
}

XML Format

The REST API plug-in supports the XML format for a response. For XML response, specify Accept: application/xml in the HTTP header as shown in the following example:

GET /api/n1k/summary HTTP/1.1
Host: 10.10.10.2
Accept: application/xml
Authorization: Basic YWRtaW46U2Zpc2gxMjM=

To specify the XML response format through cURL, use the following:

curl -u <user>:<password> <vsm-ip>/api/n1k/port-profile -H "Accept: application/xml"

The following example shows the response received in the XML format:

<?xml version="1.0" encoding="utf-8"?>
<instance url="/api/n1k/summary">
<properties>
<vcStatus>Connected</vcStatus>
<vcIpaddress>10.10.10.4</vcIpaddress>
<switchMode>Advanced</switchMode>
<ip>10.10.10.2</ip>
<vcUuid>12 57 2f 50 07 e8 b4 ea-1c 0e ba 78 23 52 96 3e</vcUuid>
<name>n1kv-cy</name>
<datacenterName>Sample-DC</datacenterName>
<haStatus>true</haStatus>
<mode>L3</mode>
<version>version 4.2(1u)SV2(2.1au) [build 4.2(1)SV2(2.1a)]</version>
<connectionName>vcenter</connectionName>
</properties>
</instance>

GET Method

The GET method lists the entities in a specific resource. The format of the GET method is as follows:

/api/n1k/<resource>

The following is an example of the GET method in cURL:

curl -u admin:password 10.10.10.2/api/n1k/port-profile/profile1 -H "Accept: application/json"

{
"profile1": {
"url": "\/api\/n1k\/port-profile\/profile1",
"properties": {
"minPorts": 1,
"description": "",
"switchportMode": "trunk",
"state": false,
"name": "profile1",
"portBinding": "static",
"portGroupName": "",
"capability": "",
"maxPorts": 32,
"type": "Vethernet"
}
}
}

POST Method

The POST method creates a new instance of a resource or updates the identified instance. To create a new resource, the format of the POST method is as follows:

/api/n1k/<resource>

The following is an example of the POST method to create an instance of a resource in cURL:

curl -X POST -u admin:password 10.10.10.2/api/n1k/port-profile -d '{ "name" : "profile1", "switchportMode" : "access", "shutdown" : false}'

Successfully created "port-profile profile1"

To modify a specific instance, the format of the POST method is as follows:

/api/n1k/<endpoint>/<instance>

The following is an example of the POST method to modify a specific instance in cURL:

curl -X POST -u admin:password 10.10.10.2/api/n1k/port-profile/profile1 -d '{ "switchportMode" : "trunk", "shutdown" : false}’

Successfully modified "port-profile profile1"

DELETE Method

The DELETE method deletes the specified instance. The format of the DELETE method is as follows:

/api/n1k/<resource>/<instance>

The following is an example of the DELETE method in cURL:

curl -u admin:password -X DELETE 10.10.10.2/api/n1k/port-profile/profile1

Successfully deleted "port-profile profile1"

/api/n1k

The APIs under /api/n1k are common for all platform.

Note

To support backward compatibility, all the APIs under /api/n1k also exist in /api/vc.

- /api/n1k/license

- /api/n1k/limits

- /api/n1k/port-profile

- /api/n1k/summary

- /api/n1k/uplink

- /api/n1k/vem

- /api/n1k/vnic

- /api/n1k/span

- /api/n1k/user

- /api/n1k/vlan

- /api/n1k/vff

- /api/n1k/vrf

- /api/n1k/vnode

- /api/n1k/vpath

- /api/n1k/vxlan

/api/n1k/license

Use this resource to get the licensing status of the Cisco Nexus 1000V switch. This resource is read-only.

Property

Example

expires

14 Sep 2013

type

NEXUS_VSG_SERVICES_PKG

available

512

status

Unused

used

0

/api/n1k/limits

Use this resource to get information about the resources available on the Cisco Nexus 1000V switch. This resource is read-only.

Property

Example

vemMax

256

vethUsed

90

vxlansUsed

529

vlansUsed

529

vemUsed

4

vxlansMax

6144

vethMax

12288

vethPerHostMax

990

vethPerHostUsed

90

vlansMax

4093

portprofilesUsed

69

portprofileMax

6144

/api/n1k/port-profile

Use this resource to create, update, and delete port-profile and view a list of configured port-profiles.

Property

Example

profileConfig

pinning id 3

description

Uplink port-profile

mtu

1500

capability

vxlan

systemVLANs

100

vserviceProfile

Vservice1

portBinding

dynamic

publishPortProfile

false

maxPorts

1024

org

cisco

vservicePath

Vservicepath1

minPorts

1

state

True

addSwitchportTrunkVLANs

100

switchportMode

Trunk

vserviceNodeName

VserviceNode1

switchportAccessBridgeDomain

Bridgedomain1

switchportTrunkNativeVLAN

101

removeSwitchportTrunkVLANs

200

inherit

Port-profile1

name

Uplink-portprofile

shutdown

False

portGroupName

Uplink-portgroup

switchportAccessVLAN

103

type

Vethernet

switchportTrunkVLANs

100

Note

Inherit will give the data for Inherited port-profile, but will not be able to push/configure inheritance.

/api/n1k/summary

Use this resource to get a summary of the Cisco Nexus 1000V switch. This resource is read-only.

Property

Example

vcStatus

Connected

vcIpaddress

10.10.10.4

switchMode

ADVANCED (3.0)

ip

10.10.10.2

vcUuid

12 57 2f 50 07 e8 b4 ea-1c 0e ba 78 23 52 96 3e

name

n1kv

datacenterName

Sample-DC

haStatus

true

mode

L3

version

version 5.2(1)SV3(1.1)

connectionName

vCenter

/api/n1k/uplink

Use this resource to get detailed information about the uplinks configured on the VSM. This resource is read-only.

Property

Example

module

4

portChannelType

Eth

packetsTx

1421

mtu

1550

packetsRx

4248

vlans

1544-1545,1590-1600,1609

portChannel

1

portChannelMembers

Ethernet4/1,Ethernet4/3

name

Ethernet4/3

ethernet

Ethernet

speed

auto-speed

mode

trunk

portProfile

vxgw-uplink

status

up

cdpPort

Ethernet100/1/32

cdpNativeVlan

1

cdpSwitch

N5k-1-14

/api/n1k/vem

Use this resource to get details of the Virtual Ethernet Modules (VEMs) attached on the VSM. This resource is read-only.

Property

Example

module

3

licenseUsage

1

esxVersion

VMware ESXi 5.0.0 Releasebuild-914586 (3.0)

ip

10.10.10.2

vethMax

990

status

ok

license

licensed

mac

Not applicable

type

Virtual Ethernet Module

numVM

71

nSockets

1

vethUsed

74

datacenterName

Sample-DC

macMax

32000

macUsed

176

version

5.2(1)SV3(1.1)

model

NA

lic_version

1.0

ports

332

name

10.10.10.2

srvuuid

0bd195e1-80cd-11df-ab4e-d0d0fd094538

/api/n1k/vnic

Use this resource to get details of the virtual Ethernet ports connected to the Cisco Nexus 1000V switch. This resource is read-only.

Property

Example

mac

0050 .56a3.0b0c

vlans

2100

vnic

Vethernet2

portGroup

vmnet-2100

status

down

adapter

Network Adapter 1

vm

Ostinato1

dvport

DVPort64

/api/n1k/span

Use this resource to create, update, and delete a session and view a list of configured sessions.

Properties

Example

id

2

type

local

sources

[{

"type": "Vethernet",

"source": ["1"],

"direction": "rx"

}]

shutdown

true

/api/n1k/user

Use this resource to create, update, and delete a user and view a list of configured users.

Property

Example

expire

14 Sep 2013

name

admin

role

network-admin

/api/n1k/vlan

Use this resource to create, update, and delete a VLAN and view a list of configured VLANS.

Property

Example

id

3603

state

active

name

vlan3603

shutdown

false

/api/n1k/vff

Use this resource to set the Anycast Gateway MAC Address and the Forwarding Mode for a Segment ID.

Property

Example

Gateway Mac

0000.dead.beef

SegId

5001

FwdMode

proxy-gateway

FwdMode

anycast-gateway

/api/n1k/vrf

Use this resource to configure VRF parameters.

Property

Example

name

management

ipRoute

10.10.10.10/24

routerInterfaceIP

10.10.10.100

shutdown

false

id

1

Note

The ipRoute and routerInterfaceIP are only writable property.

/api/n1k/vnode

Use this resource to create, update, and delete a vService node and view a list of configured vService nodes.

Property

Example

type

vsg

name

vnode-test

failmode

close

/api/n1k/vpath

Use this resource to create, update, and delete a vService path and view a list of configured vService paths.

Property

Example

name

vpath-test

nodes

[{

"order": 1,

"node": "vnode-test",

"profileName": "prof-test"

}]

/api/n1k/vxlan

Use this resource to create, update, and delete a VXLAN and view a list of configured VXLANS.

Property

Example

state

UP

macLearn

enabled

group

NULL

ports

0

mode

Unicast-only

name

TestVxlan

id

16000000

macDist

Enable

/api/n1k/vc

The APIs under /api/n1k/vc are ESX platform specific APIs.

Note

Old APIs which were under /api/vc still exist under /api/vc name space for backward compatibility.

Executing CLI via REST

To execute Nexus 1000v CLI via REST use the POST method to send an HTTP request to the following link:

http://vsm-ip/api/cli

Include the following in the request body:

{"cmd": "config t; no logging console"}

To do the same using cURL, use the following command:

curl -u username:password 10.10.10.2/api/cli -d '{"cmd": "config t; no logging console "}' –i

Saving Resource Changes

To save the running config on the bootflash in some file persistently, use the POST method to send an HTTP request to the following link:

http://vsm-ip/api/save_config

Include the following in the request body:

{" filename": "config_backup.cfg"}

To do the same using cURL, use the following command:

curl -u username:password 10.10.10.2/api/save_config -d '{" filename": " config_backup.cfg"}' –i

Increase max-port via REST

To execute Nexus 1000v CLI “vmware vem upgrade set maxports” which will increase max-ports via REST use the POST method to send an HTTP request to the following link:

http://vsm-ip/api/upgrade_maxport

Include the following in the request body:

{"upgrade": true}

To do the same using cURL, use the following command:

curl -u username:password 10.10.10.2/api/upgrade_maxport -d '{"upgrade": true}' –i

Feature History for Using the REST API Plug-in

Feature

Releases

Feature Information

Support for JSON Response Format

4.2(1)SV2(2.1a)

This feature was introduced.

Support for HTTP Methods

4.2(1)SV2(2.1a)

This feature was introduced.

Support for /api/port-profile resource

4.2(1)SV2(2.1a)

This feature was introduced.

Support for /api/span resource

4.2(1)SV2(2.1a)

This feature was introduced.

Support for /api/user resource

4.2(1)SV2(2.1a)

This feature was introduced.

Support for /api/vlan resource

4.2(1)SV2(2.1a)

This feature was introduced.

Support for /api/vnode resource

4.2(1)SV2(2.1a)

This feature was introduced.

Support for /api/vpath resource

4.2(1)SV2(2.1a)

This feature was introduced.

Support for /api/vxlan resource

4.2(1)SV2(2.1a)

This feature was introduced.

Support for /api/vff resource

4.2(1)SV2(2.2)

This feature was introduced.

Support for /api/n1k/vrf resource

5.2(1)SV3(1.1)

This feature was introduced.

Chapter 4. Configuring the REST API Plug-in

This chapter contains the following sections:

- Configuring the REST API Plug-in

Configuring the REST API Plug-in

You can configure the REST API plug-in and dynamically load content.

Procedure

Command or Action

Purpose

Step 1

switch (config)# plugin unload plugin_name

Unloads the REST API plug-in completely from the system.

Note:
After unloading the REST API plug-in, wait for at least 10 seconds before you proceed to the next step to load the REST API plug-in.

Note:
When you unload the default REST API plug-in, the only way to reinstall the REST API plug-in is from the Cisco website and then load it on the Cisco Nexus 1000V switch.

Step 2

switch (config)# plugin load location

Loads the REST API plug-in.

Note:
When the VSM is in HA pair, ensure the REST API plug-in image is available on both the supervisors. Copying the file to bootflash://sup-standby/ copies the file to the standby VSM.

Note:
When a new plugin is loaded from the bootflash, the plugin file should not be removed from Active or Standby VSM.

Step 3

switch (config)# show plugin status

Displays the status of all the plug-ins installed in the system.

This example shows how to unload and load the REST API plug-in:

switch(config)# plugin unload rest
switch(config)#  plugin load bootflash:///rest_sup1sf.gbin

This example shows how to display the status of the installed plug-in:

switch(config) # show plugin status
Plugin-name                Version            Status
-------------------------  -----------------  -----------------
Rest Plugin                1.0(1)             Loaded

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)