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/vc/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/port-profile -H "Accept: application/json"
The following example shows the response received in the JSON format:
HTTP/1.1 200 OK Date: Wed, 21 Aug 2013 19:33:56 GMT Content-Type: application/json; charset=utf-8 { "": { "url": "/api/vc/summary", "properties": { "vcStatus": "Connected", "vcIpaddress": "10.10.10.4", "switchMode": "Advanced", "ip": "10.10.10.2", "vcUuid": "12 57 2f 50 07 e8 b4 ea-1c 0e ba 78 23 52 96 3e", "name": "n1kv-cy", "datacenterName": "Sample-DC", "haStatus": true, "mode": "L3", "version": "version 4.2(1u)SV2(2.1au) [build 4.2(1)SV2(2.1a)]", "connectionName": "vcenter" } } }
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/vc/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/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/vc/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/<resource>
The following is an example of the GET method in cURL:
curl -u admin:password 10.10.10.2/api/port-profile/profile1 -H "Accept: application/json" { "profile1": { "url": "\/api\/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/<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/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/<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/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/<resource>/<instance>
The following is an example of the DELETE method in cURL:
curl -u admin:password -X DELETE 10.10.10.2/api/port-profile/profile1 Successfully deleted "port-profile profile1"
Cisco Nexus 1000V REST API Resources
Use this resource to create, update, delete, and view a list of port-profiles.
Property | Example |
---|---|
minPorts |
1 |
description |
Profile for VLAN 3603 |
switchportMode |
access |
capability |
l3control |
state |
false |
switchportAccessVLAN |
3603 |
name |
vlan3603 |
shutdown |
false |
portGroupName |
vlan3603 |
portBinding |
static |
maxPorts |
32 |
type |
vethernet |
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" }] |
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 |
The APIs under /api/vc are used internally by the Cisco Nexus 1000V vCenter plug-in and are read-only. These APIs are changed according to the requirements of the Cisco Nexus 1000V vCenter plug-in.
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 |
128 |
vethUsed |
90 |
vxlansUsed |
529 |
vlansUsed |
529 |
vemUsed |
4 |
vxlansMax |
2048 |
vethMax |
4096 |
vethPerHostMax |
300 |
vethPerHostUsed |
90 |
vlansMax |
2048 |
portprofilesUsed |
69 |
portprofileMax |
2048 |
Use this resource to get details of the port profiles configured on the VSM. This resource is read-only.
Property | Example |
---|---|
module |
3, 7 |
minPorts |
1 |
systemVlans |
1609 |
usedPorts |
6 |
name |
up1 |
type |
Ethernet |
status |
1 |
mode |
trunk |
maxPorts |
32 |
vlans |
1544-1545,1590-1600,1609, 2100 |
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 |
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 4.2(1)SV2(2.1a) |
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 |
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 |
300 |
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 |
4.2(1)SV2(2.1a) |
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 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 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 |
id |
16000000 |
macDist |
Enable |
To make the changes done for a resource (through POST or DELETE method) persistent, 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": "copy r s"}
To do the same using cURL, use the following command:
curl -u username:password 10.10.10.2/api/cli -d '{"cmd": "copy r s"}' -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. |