The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter contains the following sections:
Supported Response Formats
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" } } }
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>
Supported HTTP Methods
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" } } }
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"
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"
Cisco Nexus 1000V REST API Resources
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. |
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 |
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 |
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. |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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. |
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 |
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" }] |
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 |
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. |
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
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
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 |
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. |