NX-API Developer Sandbox

• About the NX-API Developer Sandbox, on page 1

• Guidelines and Restrictions for the Developer Sandbox, on page 2
• Configuring the Message Format and Command Type, on page 2
• Using the Developer Sandbox, on page 4
• Using the Developer Sandbox to Convert CLI Commands to REST Payloads, on page 4
• Using the Developer Sandbox to Convert from REST Payloads to CLI Commands, on page 7

About the NX-API Developer Sandbox

The NX-API Developer Sandbox is a web form hosted on the switch. It translates NX-OS CLI commands
into equivalent XML or JSON payloads, and converts NX-API REST payloads into their CLI equivalents.
The web form is a single screen with three panes — Command (top pane), Request, and Response — as shown
in the figure.
Figure 1: NX-API Developer Sandbox with Example Request and Output Response

NX-API Developer Sandbox

1
 NX-API Developer Sandbox
Guidelines and Restrictions for the Developer Sandbox

Controls in the Command pane allow you to choose a message format for a supported API, such as NX-API
REST, and a command type, such as XML or JSON. The available command type options vary depending
on the selected message format.
When you type or paste one or more CLI commands into the Command pane, the web form converts the
commands into an API payload, checking for configuration errors, and displays the resulting payload in the
Request pane. If you then choose to post the payload directly from the Sandbox to the switch, using the POST
button in the Command pane, the Response pane displays the API response.
Conversely, when you type an NX-API REST designated name (DN) and payload into the Command pane
and select the nx-api rest Message format and the model Command type, Developer Sandbox checks
the payload for configuration errors, then the Response pane displays the equivalent CLIs.

Guidelines and Restrictions for the Developer Sandbox

• Clicking POST in the Sandbox commits the command to the switch, which can result in a configuration
or state change.
• Some feature configuration commands are not available until their associated feature has been enabled.

Configuring the Message Format and Command Type

The Message Format and Command Type are configured in the upper right corner of the Command pane
(the top pane). For Message Format, choose the format of the API protocol that you want to use. The Developer
Sandbox supports the following API protocols:

Table 1: NX-OS API Protocols

Protocol Description

json-rpc A standard lightweight remote procedure call (RPC) protocol that can be used to deliver
NX-OS CLI commands in a JSON payload. The JSON-RPC 2.0 specification is outlined
by jsonrpc.org.

xml Cisco NX-API proprietary protocol for delivering NX-OS CLI or bash commands in
an XML payload.

json Cisco NX-API proprietary protocol for delivering NX-OS CLI or bash commands in
a JSON payload.

nx-api rest Cisco NX-API proprietary protocol for manipulating and reading managed objects
(MOs) and their properties in the internal NX-OS data management engine (DME)
model. For more information about the Cisco Nexus 3000 and 9000 Series NX-API
REST SDK, see https://developer.cisco.com/site/cisco-nexus-nx-api-references/.

nx yang The YANG ("Yet Another Next Generation") data modeling language for configuration
and state data.

When the Message Format has been chosen, a set of Command Type options are presented just below the
Message Format control. The Command Type setting can constrain the input CLI and can determine the

NX-API Developer Sandbox

2
NX-API Developer Sandbox
Configuring the Message Format and Command Type

Request and Response format. The options vary depending on the Message Format selection. For each
Message Format, the following table describes the Command Type options:

Table 2: Command Types

Message format Command type

json-rpc • cli — show or configuration commands

• cli-ascii — show or configuration commands, output without
formatting

xml • cli_show — show commands. If the command does not support

XML output, an error message will be returned.
• cli_show_ascii — show commands, output without formatting
• cli_conf — configuration commands. Interactive configuration
commands are not supported.
• bash — bash commands. Most non-interactive bash commands are
supported.
Note The bash shell must be enabled in the switch.

json • cli_show — show commands. If the command does not support

XML output, an error message will be returned.
• cli_show_ascii — show commands, output without formatting
• cli_conf — configuration commands. Interactive configuration
commands are not supported.
• bash — bash commands. Most non-interactive bash commands are
supported.
Note The bash shell must be enabled in the switch.

nx-api rest • cli — configuration commands

• model — DN and corresponding payload.

nx yang • json — JSON structure is used for payload

• xml — XML structure is used for payload

Output Chunking
In order to handle large show command output, some NX-API message formats support output chunking for
show commands. In this case, an Enable chunk mode checkbox appears below the Command Type control
along with a session ID (SID) type-in box.
When chunking is enabled, the response is sent in multiple "chunks," with the first chunk sent in the immediate
command response. In order to retrieve the next chunk of the response message, you must send an NX-API
request with SID set to the session ID of the previous response message.

NX-API Developer Sandbox

3
 NX-API Developer Sandbox
Using the Developer Sandbox

Using the Developer Sandbox

Using the Developer Sandbox to Convert CLI Commands to REST

Payloads

Tip Online help is available by clicking Quick Start in the upper right corner of the Sandbox window.
Additional details, such as response codes and security methods, can be found in the chapter "NX-API CLI".
Only configuration commands are supported.

Procedure

Step 1 Configure the Message Format and Command Type for the API protocol you want to use.
For detailed instructions, see Configuring the Message Format and Command Type, on page 2.

Step 2 Type or paste NX-OS CLI configuration commands, one command per line, into the text entry box in the top
pane.
You can erase the contents of the text entry box (and the Request and Response panes) by clicking Reset at
the bottom of the top pane.

NX-API Developer Sandbox

4
NX-API Developer Sandbox
Using the Developer Sandbox to Convert CLI Commands to REST Payloads

Step 3 Click the Convert at the bottom of the top pane.

If the CLI commands contain no configuration errors, the payload appears in the Request pane. If errors are
present, a descriptive error message appears in the Response pane.

NX-API Developer Sandbox

5
 NX-API Developer Sandbox
Using the Developer Sandbox to Convert CLI Commands to REST Payloads

Step 4 When a valid payload is present in the Request pane, you can click POST to send the payload as an API call
to the switch.
The response from the switch appears in the Response pane.
Warning Clicking POST commits the command to the switch, which can result in a configuration or state
change.

NX-API Developer Sandbox

6
 NX-API Developer Sandbox
Using the Developer Sandbox to Convert from REST Payloads to CLI Commands

Step 5 You can copy the contents of the Request or Response pane to the clipboard by clicking Copy in the pane.
Step 6 You can obtain a Python implementation of the request on the clipboard by clicking Python in the Request
pane.

Using the Developer Sandbox to Convert from REST Payloads

to CLI Commands

Tip Online help is available by clicking Quick Start in the upper right corner of the Sandbox window.
Additional details, such as response codes and security methods, can be found in the chapter "NX-API CLI".

Procedure

Step 1 Select nx-api rest as the Message Format and model as the Command Type.
Example:

NX-API Developer Sandbox

7
 NX-API Developer Sandbox
Using the Developer Sandbox to Convert from REST Payloads to CLI Commands

Step 2 Enter a DN and payload into the text entry box in the top pane. Then click on the Convert button below the
top pane.
Example:
For this example, the DN is api/mo/sys.json and the NX-API REST payload is:
{
"topSystem": {
"attributes": {
"name": "REST2CLI"
}
}
}

NX-API Developer Sandbox

8
NX-API Developer Sandbox
Using the Developer Sandbox to Convert from REST Payloads to CLI Commands

When you click on the Convert button, the CLI equivalent appears in the CLI pane as shown in the following
image.

NX-API Developer Sandbox

9
 NX-API Developer Sandbox
Using the Developer Sandbox to Convert from REST Payloads to CLI Commands

NX-API Developer Sandbox

10
NX-API Developer Sandbox
Using the Developer Sandbox to Convert from REST Payloads to CLI Commands

Note The Developer Sandbox cannot convert all payloads into equivalent CLIs, even if the Sandbox
converted the CLIs to NX-API REST payloads. The following is a list of possible sources of error
that can prevent a payload from completely converting to CLI commands:

Table 3: Sources of REST2CLI Errors

Payload Issue Result

The payload contains an attribute that does not The Error pane will return an error related to
exist in the MO. the attribute.
Example: Example:
api/mo/sys.json CLI
{
"topSystem": { Error unknown attribute
"children": [ 'fakeattribute' in element
{
"interfaceEntity": { 'l1PhysIf'
"children": [
{
"l1PhysIf": {
"attributes": {
"id": "eth1/1",
"fakeattribute":
"totallyFake"
}
}
}
]
}
}
]
}
}

The payload includes MOs that aren't yet The Error Pane will return an error related to
supported for conversion: the unsupported MO.
Example: Example:
api/mo/sys.json CLI
{
"topSystem": { Error The entire subtree of
"children": [ "sys/dhcp" is not converted.
{
"dhcpEntity": {
"children": [
{
"dhcpInst": {
"attributes": {
"SnoopingEnabled": "yes"

}
}
}
]
}
}
]
}
}

NX-API Developer Sandbox

11
 NX-API Developer Sandbox
Using the Developer Sandbox to Convert from REST Payloads to CLI Commands

NX-API Developer Sandbox

12