Cisco Nexus 1000V REST API Plug-in Configuration Guide, Release 5.2(1)SV3(1.1)
Using the REST API Plug-in
Downloads: This chapterpdf (PDF - 1.16MB) The complete bookPDF (PDF - 2.13MB) | The complete bookePub (ePub - 176.0KB) | The complete bookMobi (Mobi - 277.0KB) | Feedback

Using the REST API Plug-in

Using the REST API Plug-in

This chapter contains the following sections:

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:

HTTP/1.1 200 OK
Date: Wed, 21 Aug 2013 19:33:56 GMT
Content-Type: application/json; charset=utf-8
{
    "": {
        "url": "/api/n1k/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"
        }
    }
}

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

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