How to Use this Reference

The Nexus Model Reference is a resource to help you browse data models to understand the purpose of each model, how to access it, and the type of data contained in it.

Model Driven Programming Workflow

  1. Consult NX-API REST SDK User Guide for information on how to access models through REST.
  2. You can follow recipes provided in the above guide to configure or query different features of the system.
  3. Use this reference for detailed information about classes and attributes described in the payload.

NX-API Model Information

Each page in this reference shows the following information:

  1. Model Name and Description
  2. Telemetry Sensor Path (Model URI)
  3. Configurable Attributes
  4. Operational Attributes
  5. Ephemeral Attributes
  6. Internal Attributes

Accessing Model Objects through REST

What you will need

  • A supported Nexus switch with feature nxapi configured.
  • Your preferred REST client.

Sequence of Configuration

1. Authenticate

Issue a POST to https://[IP of Nexus switch]/api/mo/aaaLogin.json with the below example payload. 

{"aaaUser" : {"attributes" : {"name": "USERNAME","pwd": "PASSWORD"}}}

This call returns a cookie value that the client uses for the next calls.

2. POST Configuration

Send HTTP POST to apply the configuration: The URL of the POST message varies depending on the object, the following is an example: https://[IP of Nexus switch]//api/mo/sys/bgp/inst.json, where api indicates that this call is to the API, mo indicates that this call is to modify a managed object, bgp/inst refers to the BGP instance, and .json indicates that the payload is in JSON format. If the end of URL were .xml, that would mean that the payload is in XML format.

3. GET Configuration/Operational Data

Send HTTP GET to get an XML or JSON payload containing configuration and operational data.

For Example:

  1. From l1:PhysIf reference page. We can see the Sensor Path (URI) is sys/intf/phys-[name].
  2. With that information, we know the full URL for our REST query to get JSON data is http://[IP]/api/mo/sys/intf/phys-[eth1/1].json
  3. Issuing an HTTP get would give the following payload as an example: 
{
    "totalCount": "1",
    "imdata": [
        {
            "l1PhysIf": {
                "attributes": {
                    "accessVlan": "vlan-100",
                    "adminSt": "up",
                    "autoNeg": "on",
                    "beacon": "off",
                    "bw": "default",
                    "childAction": "",
                    "controllerId": "",
                    "delay": "1",
                    "descr": "",
                    "dn": "sys/intf/phys-[eth1/1]",
                    "dot1qEtherType": "0x8100",
                    "duplex": "auto",
                    "ethpmCfgFailedBmp": "",
                    "ethpmCfgFailedTs": "00:00:00:00.000",
                    "ethpmCfgState": "0",
                    "id": "eth1/1",
                    "inhBw": "4294967295",
                    "layer": "Layer2",
                    "linkDebounce": "100",
                    "linkLog": "default",
                    "mdix": "auto",
                    "medium": "broadcast",
                    "modTs": "2017-11-01T11:04:30.738+00:00",
                    "mode": "access",
                    "monPolDn": "uni/infra/moninfra-default",
                    "mtu": "1500",
                    "name": "",
                    "nativeVlan": "vlan-1",
                    "persistentOnReload": "true",
                    "portT": "leaf",
                    "routerMac": "not-applicable",
                    "snmpTrapSt": "enable",
                    "spanMode": "not-a-span-dest",
                    "speed": "auto",
                    "speedGroup": "auto",
                    "status": "",
                    "switchingSt": "disabled",
                    "trunkLog": "default",
                    "trunkVlans": "1-4094",
                    "uid": "0",
                    "usage": "discovery",
                    "userCfgdFlags": "admin_layer,admin_state",
                    "vlanmgrCfgFailedBmp": "",
                    "vlanmgrCfgFailedTs": "17471:19:04:37.000",
                    "vlanmgrCfgState": "0",
                    "voicePortCos": "none",
                    "voicePortTrust": "disable",
                    "voiceVlanId": "none",
                    "voiceVlanType": "none"
                }
            }
        }
    ]
}
4. Issuing a GET for a model and all its children

NX-API REST provides a special URL parameter (rsp-subtree=full) that returns a model and all its children.

For example:

GET http://[IP]/api/mo/sys/intf/phys-[eth1/1].json?rsp-subtree=full
5. Issuing a GET for ephemeral only properties

NX-API REST provides a special URL parameter (rsp-foreign-subtree=ephemeral) to return only ephemeral properties.

For the query to work: 1. The requested model must be an ephemeral model. 2. URL parameters must also include batch-size and batch-id. 3. Ephemeral data must be present.

For example:

GET http://[IP]/api/mo/sys/mrib/inst/routeDb.json?rsp-foreign-subtree=ephemeral&batch-size=110&batch-id=1
6. Special URL Parameters

Here is a list of url parameters supported by NX-API and their equivalent uses.

URL Parameter Value Result
rsp-subtree full Entire tree starting from the requested model.
rsp-subtree children Only the requested model and its children.
rsp-foreign-subtree ephemeral Only ephemeral properties. (works with ephemeral models only)
rsp-prop-include config-only Only configuration properties.

For a full list of URL parameters, check the REST API Configuration Guide.

Supported Platforms

A list of supported platforms can be found here.

Contact Us For Feedback

To provide feedback on this document, or to report an error or omission, please send your comments to nexus9k-docfeedback@cisco.com. We appreciate your feedback.