Cisco Nexus 3000 and 9000 Series NX-API REST SDK User Guide and API Reference, Release 10.5(x)
Loading...
NX-API REST Management Commands
Commands
Copy

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

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:

](http://mmattozzi.github.io/cocoa-rest-client/)

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.

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

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. To determine the filter options, send an OPTIONS request; this returns a response payload with a list of possible filter options as demonstrated in the payload on the right. You can use these options to construct a query. For example, the payload in the pane on the right says that the rsp-subtree= can be used with the type full. The payload also lists rsp-prop-include, which can be used with the type config-only. Joining these with an ampersand creates a filter that you can attach for a query: GET http://<mgmt_0>/api/mo/sys.json?rsp-subtree=full&rsp-prop-include=config-only. For more information, see Applying Query Scoping Filters below.

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.

This section uses example GET requests to demonstrate how to apply query-scoping filters.

Note: These example payloads are requesting information provided by the following BGP cofiguration:

router bgp 100  router-id 10.11.11.1  log-neighbor-changes  address-family ipv4 unicast  neighbor 10.11.11.5   remote-as 100   timers 5 15  vrf vrf1   router-id 10.11.11.10

Querying by Target (Self)

Querying by Target (Self)

Querying by Target (Children)

Querying by Target (Children)

Querying by Filter String

Querying by Filter String

Querying by Target Tree (Running)

Querying by Target Tree (Running)

Querying by Target Tree (Candidate)

Querying by Target Tree (Candidate)

Querying by Target Tree (Applied)

Querying by Target Tree (Applied)

Querying to Include Hidden Properties

Querying to Include Hidden Properties

Querying the Depth of Subtree in Response

Querying the Depth of Subtree in Response

Querying the Depth of Ancestor in Response

Querying the Depth of Ancestor in Response

Querying to Show No Tree in Response

Querying to Show No Tree in Response

Querying to Show Only Children in Response

Querying to Show Only Children in Response

Querying to Show Full Tree in Response

Querying to Show Full Tree in Response

Querying to Turn on Matching Only in Response

Querying to Turn on Matching Only in Response

Querying to Include Tasks in Response

Querying to Include Tasks in Response

Querying to Include Faults in Response

Querying to Include Faults in Response

Querying to Include Health in Response

Querying to Include Health in Response

Querying to Include Stats in Response

Querying to Include Stats in Response

Querying to Include Relations in Response

Querying to Include Relations in Response

Querying to Include Relations With the Parent in Response

Querying to Include Relations With the Parent in Response

Querying to Include Record Subtree in Response

Querying to Include Record Subtree in Response

Querying to Include No Scoping in Response

Querying to Include No Scoping in Response

Querying to Include Record Subtree in Response

Querying to Include Record Subtree in Response

Querying to Include Fault Records in Response

Querying to Include Fault Records in Response

Querying to Include Deployment in Response

Querying to Include Deployment in Response

Querying to Include Port Deployment in Response

Querying to Include Port Deployment in Response

Querying to Include Health Records in Response

Querying to Include Health Records in Response

Querying to Include Audit Logs in Response

Querying to Include Audit Logs in Response

Querying to Include Event Logs in Response

Querying to Include Event Logs in Response

Querying to Include Required in Response

Querying to Include Required in Response

Querying to Include Count in Response

Querying to Include Count in Response

Querying to Include Fault Count in Response

Querying to Include Fault Count in Response

Querying to Include Properties in Response (All)

Querying to Include Properties in Response (All)

Querying to Include Properties in Response (Naming Only)

Querying to Include Properties in Response (Naming Only)

Querying to Include Properties in Response (Config Only)

Querying to Include Properties in Response (Config Only)

Querying to Include Properties in Response (Set Config Only)

Querying to Include Properties in Response (Set Config Only)

Querying to Include Properties in Response (Nondefault Config Only)

Querying to Include Properties in Response (Nondefault Config Only)

Querying a Subtree Filter String

Querying a Subtree Filter String

Querying a Foreign Subtree (None)

Querying a Foreign Subtree (None)

Querying a Foreign Subtree (Applied Config)

Querying a Foreign Subtree (Applied Config)

Querying a Foreign Subtree (Ephemeral)

Querying a Foreign Subtree (Ephemeral)

For an example of an ephemeral query, see Querying IP IGMP Groups.

Querying to Keep the Property Type

Querying to Keep the Property Type

Querying by Batch Id

Querying by Batch Id

For an example of querying by batch Id, see see Querying IP IGMP Groups.

Querying by Batch Size

Querying by Batch Size

For an example of querying by batch size, see see Querying IP IGMP Groups.

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.
  • Code section - 46
  • 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.
  • Code section - 47
  • 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.

Operator Description
eq Equal to
ne Not equal to
lt Less than
gt Greater than
le Less than or equal to
ge Greater than or equal to
bw Between
not Logical inverse
and Logical AND
or Logical OR
xor Logical exclusive OR
true Boolean TRUE
false Boolean FALSE
anybit TRUE if at least one bit is set
allbits Wildcard
pholder Property holder
passive Passive holder
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.

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
Attribute Description Naming property (y/n) Type Acceptable values (numeric values) Default Values
adminSt The administrative state of the object or policy N Enum enabled (1) disabled (2) disabled(2)

Corresponding CLI

switch(config)# feature nxapi

Operational properties

Oper data

Attribute Description Type Acceptable values (numeric values) Default Values
operSt The runtime state of the object Enum enabled disabled disabled
maxInstance Number of instances configured Uint32 1 1

Retries
None

Faults
None

Show CLI
show feature

Next