Using the REST API Plug-in

This chapter contains the following sections:

• Supported Response Formats, page 1

• Supported HTTP Methods, page 2
• Cisco Nexus 1000V REST API Resources, page 3
• Executing CLI via REST, page 12
• Saving Resource Changes, page 12
• Increase max-port via REST, page 13
• Feature History for Using the REST API Plug-in, page 13

Supported Response Formats

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",

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
1
 Using the REST API Plug-in
XML Format

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

Supported HTTP Methods

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",

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
2
 Using the REST API Plug-in
POST Method

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

Cisco Nexus 1000V REST API Resources

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

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
3
 Using the REST API Plug-in
/api/n1k

/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

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
4
Using the REST API Plug-in
/api/n1k

/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

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
5
 Using the REST API Plug-in
/api/n1k

Property Example
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

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
6
Using the REST API Plug-in
/api/n1k

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

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
7
 Using the REST API Plug-in
/api/n1k

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.

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
8
Using the REST API Plug-in
/api/n1k

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

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
9
 Using the REST API Plug-in
/api/n1k

Property Example
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

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
10
Using the REST API Plug-in
/api/n1k

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

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
11
 Using the REST API Plug-in
/api/n1k/vc

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"}

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
12
 Using the REST API Plug-in
Increase max-port via REST

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 4.2(1)SV2(2.1a) This feature was introduced.
Format

Support for HTTP Methods 4.2(1)SV2(2.1a) This feature was introduced.

Support for /api/port-profile 4.2(1)SV2(2.1a) This feature was introduced.

resource

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.

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
13
 Using the REST API Plug-in
Feature History for Using the REST API Plug-in

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x
14