Getting Started with the Cisco Nexus 3000 and 9000 Series NX-API REST SDK

Using NX-API REST with the Cisco Nexus 3000 and 9000 Series switches requires the following main steps:

1. Enabling NX-API REST on the switch, which allows communication with the switch using HTTP calls.
2. Installing and Using a REST Client. You can use a variety of REST clients to run NX-API REST. For example, Postman is provided as a free download for Google Chrome, and allows you to build and issue HTTP requests that execute the NX-API REST APIs to configure the switch. For details on using REST clients, see the "Running the APIs" section below.
3. Verifying the Configuration. After you execute one or more HTTP requests to execute NX-API REST calls, you should verify that the configuration is active by issuing GET commands from your REST client or appropriate CLI commands at the switch console.
4. Optionally, you can use the NX-API REST API from the Guest Shell.

NX-API REST is available for use with the Cisco Nexus 3132Q-XL, 3172PQ-XL, and 3172TQ-XL switches [starting with Cisco NX-OS Release 7.0(3)I2(2)], the Cisco Nexus 3164Q and 31128PQ switches, and the Cisco Nexus 9000 Series switches. NX-API REST is not supported for other Cisco Nexus 3000 and 3100 Series switches.

NX-API REST Management Commands

This section lists CLI commands that enable and configure NX-API REST on the switch.

Enabling NX-API REST on the Switch

To enable NX-API, enter the following CLI command on the switch:

feature nxapi

NX-API REST and the DME database are now enabled.

By default, the NX-API REST feature is enabled for HTTP listen on port 80 and HTTPS listen on port 443. If you need to change the HTTP or HTTPS port, you can use the nxapi port command.

Enabling and Disabling HTTP Ports for NX-API REST

By default, when you enable the NX-API REST feature, NX-API REST is configured for HTTP listen on port 80 and HTTPS listen on port 443.

To change the listen ports, use the following command:

nxapi {http | https} port port_number

where port_number specifies the port number to use for HTTP listen or HTTPS listen.

To disable a specified port enter the following command:

no nxapi {http | https}

Specifying http disables the active HTTP port and specifying https disables the active HTTPS port.

Uploading and Enabling Certificates

If you want to use a security certificate to authenticate users of NX-API REST, you must upload a certificate and then enable it.

To upload a certificate, enter the following command:

nxapi certificate {httpscrt | httpskey}

where:

• httpscrt specifies uploading an HTTPS certificate.
• httpskey specifies uploading an HTTPS key.

To enable the certificate or key, enter the following command;

nxapi certificate enable

Querying the NX-API REST Configuration

To display the current NX-API REST configuration, enter the following command:

show nxapi

The console indicates whether NX-API REST is enabled and indicates the listen ports:

nxapi enabled HTTP Listen on port 80 HTTPS Listen on port 443

VRF Commands

nxapi use-vrf

Specifies the default VRF, management VRF, or named VRF.

Iptables is a command-line firewall utility that uses policy chains to allow or block traffic and almost always comes pre-installed on any Linux distribution.

ip netns exec management iptables

Implements any access restrictions and can be run in management VRF.

Running the APIs

You can use a number of commercially available and freeware REST clients to issue HTTP requests using NX-API REST. Some commonly used REST clients are:

• Postman: Postman is a developer utility that allows you to construct and issue HTTP requests. There are many versions; for example, Google provides Google Postman Extension for Chrome, which is downloadable from the Google Chrome Store. You can download the Google Postman Extension for Chrome from the Chrome Store at the following URL:

  https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en]

• Cocoa REST Client: A freeware REST client that runs on the MAC OS. You can download the Cocoa REST Client from the following URL:

  http://mmattozzi.github.io/cocoa-rest-client/

• RESTtest: A MAC-OS app that lets you test REST clients. This app is available on the Apple Mac App Store. You can download RESTtest from the following URL:

  https://itunes.apple.com/us/app/resttest/id428847656?mt=12

There are many other Postman products or REST clients that you can use to issue NX-API REST HTTP requests.

Entering URLs

URLs represent endpoints for the HTTP communication that transfers the HTTP request. The target endpoint for an NX-API REST call is the IP address or hostname of a Nexus 3000 or 9000 switch.

Header

You can use the sample URLs provided in this document by pasting the URL into the Postman URL input field or clicking a saved URL in the list of saved requests or collections at the left of the Postman display. Or if you know the object IDs stored in the DME database, you can use the Postman key-value editor to construct the URL.

HTTP Methods

With Postman, you can select the HTTP method from the Postman method pull-down. With other REST clients, you use the client user interface to specify the method type.

With NX-API REST, you will send a GET, a POST, or a DELETE.

HTTP GET

The GET method retrieves data from a specified MO on the switch.

POST

The POST method writes data to the MO database on the switch.

HTTP DELETE

The DELETE method deletes a specified configuration. For example, you can delete a switch user.

Message Body

The Message body (payload) contains JSON code that specifies the data for the HTTP method.

Message Response

The message response is an HTTP return code and an HTTP Response Body that contains JSON code showing the data returned by the method.

Filtering API Query Results

You can filter the results of an API query by appending one or more condition statements to the query URL as a parameter in this format:

https://URI?condition[&condition[&...]]

Multiple condition statements are joined by an ampersand (&).

Options are available to filter by object attributes and object subtrees.

Applying Query Scoping Filters

You can limit the scope of the response to an API query by applying scoping filters. You can limit the scope to the first level of an object or to one or more of its subtrees or children based on the class, properties, categories, or qualification by a logical filter expression.

query-target={self | children | subtree}

This statement restricts the scope of the query. This list describes the available scopes:

• self—(Default) Considers only the MO itself, not the children or subtrees.

• children—Considers only the children of the MO, not the MO itself.

• subtree—Considers the MO itself and its subtrees.

target-subtree-class=mo-class1[,mo-class2]...

This statement specifies which object classes are to be considered when the query-target option is used with a scope other than self. You can specify multiple desired object types as a comma-separated list with no spaces.

To request subtree information, combine query-target=subtree with the target-subtree-class statement to indicate the specific subtree as follows:

query-target=subtree&target-subtree-class=className

query-target-filter=filter-expression

This statement specifies a logical filter to be applied to the response. This statement can be used by itself or applied after the query-target statement.

rsp-subtree={no | children | full}

For objects returned, this option specifies whether child objects are included in the response. This list describes the available choices:

• no—(Default) Response includes no children.
• children—Response includes only the children.
• full—Response includes the entire structure including the children.

rsp-subtree-class=mo-class

When child objects are to be returned, this statement specifies that only child objects of the specified object class are included in the response.

rsp-subtree-filter=filter-expression

When child objects are to be returned, this statement specifies a logical filter to be applied to the child objects.

rsp-subtree-include=category1[,category2...][option]

When child objects are to be returned, this statement specifies additional contained objects or options to be included in the response. You can specify one or more of the following categories in a comma-separated list with no spaces:

• audit-logs—Response includes subtrees with the history of user modifications to managed objects.
• event-logs—Response includes subtrees with event history information.
• faults—Response includes subtrees with currently active faults.
• fault-records—Response includes subtrees with fault history information.
• health—Response includes subtrees with current health information.
• health-records—Response includes subtrees with health history information.
• relations—Response includes relations-related subtree information.
• stats—Response includes statistics-related subtree information.
• tasks—Response includes task-related subtree information.

With any of the preceding categories, you can also specify one of the following options to further refine the query results:

• count—Response includes a count of matching subtrees but not the subtrees themselves.
• no-scoped—Response includes only the requested subtree information. Other top-level information of the target MO is not included in the response.
• required—Response includes only the managed objects that have subtrees matching the specified category.

For example, to include fault-related subtrees, specify faults in the list. To return only fault-related subtrees and no other top-level MO information, specify faults,no-scoped in the list as shown in this example:

query-target=subtree&rsp-subtree-include=faults,no-scoped

rsp-prop-include={all | naming-only | config-only}

This statement specifies what type of properties should be included in the response when the rsp-subtree option is used with an argument other than no.

• all—Response includes all properties of the returned managed objects.
• naming-only—Response includes only the naming properties of the returned managed objects.
• config-only—Response includes only the configurable properties of the returned managed objects.

Composing Query Filter Expressions

You can filter the response to an API query by applying an expression of logical operators and values. A basic equality or inequality test is expressed as follows:

query-target-filter=[eq|ne](attribute,value)

You can create a more complex test by combining operators and conditions using parentheses and commas:

query-target-filter=[and|or]([eq|ne](attribute,value),[eq|ne](attribute,value),...)

Available Logical Operators

The following table lists the available logical operators for query filter expressions.

Examples

This example returns all managed objects of class aaaUser whose last name is equal to "Washington":

GET https://<IP_Address>/api/class/aaaUser.json? query-target-filter=eq(aaaUser.lastName,"Washington")

This example returns aaa:Domain objects whose names are not "infra" or "common":

GET https://<IP_Address>/api/class/aaaDomain.json? query-target-filter= and(ne(aaaDomain.name,"infra"), ne(aaaDomain.name,"common"))

Verifying the Configuration

To verify the configuration, do one of the following:

• If you issued an POST call, issue an HTTP GET querying the managed object addressed in the POST operation.

• Issue an NX-OS show command that shows the result of the command or commands that you used to enable configuration settings.

  For example, if you issued a http://<IP address>/api/mo/sys/bgp/inst.json command to set BGP configuration values, you could issue the show running-config bgp command to display the BGP configuration and verify it.

• Use the Visore browser to navigate to the MO that holds the configuration that you specified using an POST method and verify that the attributes of the object are correct.

  For more information, see the "Using the Managed Object Browser" section.

Using the Developer Sandbox

The NX-API Developer Sandbox is a web form, hosted on the switch, that can translate NX-OS CLI commands into equivalent JSON or XML payloads that can be pushed to the NX-API REST API. The web form is a single screen with three panes — Command (top pane), Request, and Response — as shown in the figure.

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.

For detailed instructions on using the NX-API Developer Sandbox, see the Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x.

NX-API Feature Model

Hierarchy

• fm:Entity (sys/fm)
  • fm:Nxapi (sys/fm/nxapi)

Supported Configuration

• Configuring feature nxapi in config mode
• Managed Object: fm:Nxapi

Corresponding CLI

switch(config)# feature nxapi

Operational properties

Oper data

Retries
None

Faults
None

Show CLI
show feature