Cisco Nexus 1000V REST API Plug-in Configuration Guide, Release 4.2(1)SV2(2.1a)
Using the REST API Plug-in
Downloads: This chapterpdf (PDF - 1.16MB) The complete bookPDF (PDF - 2.17MB) | The complete bookePub (ePub - 176.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/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"
        }
    }
}

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

GET Method

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

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

DELETE Method

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

/api/port-profile

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

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

}]

/api/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/vc

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.

/api/vc/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/vc/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

128

vethUsed

90

vxlansUsed

529

vlansUsed

529

vemUsed

4

vxlansMax

2048

vethMax

4096

vethPerHostMax

300

vethPerHostUsed

90

vlansMax

2048

portprofilesUsed

69

portprofileMax

2048

/api/vc/port-profile

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

/api/vc/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

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

/api/vc/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

/api/vc/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

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

/api/vc/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/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/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/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/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

id

16000000

macDist

Enable

Saving Resource Changes

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