Getting Started

The following sections introduce you to the standard Nexus Dashboard and services REST API operations, provide information on how to access the in-product API reference, and describe how to compose and test simple API calls to get you started.

The following standard REST methods are supported by Nexus Dashboard REST API:

• POST - For resource creations and actions.
• PUT - For resource updates.
• DELETE - For resource deletions.
• GET - For reading resources.
• The REST interface requires JSON payloads. However, APIC API proxy operations accept either JSON or XML.

A typical REST API operation consists of three elements:

• Request URL — The address of the resource to which you make the API call.

• Request message — The JSON-formatted payload that contains the new data you want to add or update. For read-only operation (GET) the request message is empty.

• Request response — The JSON-formatted response that contains the requested information.

Accessing API Reference

The complete API reference is available directly in the product at the following URL:

https://<nd-node-ip>/help-center/swagger/

The same API reference is also available online at the Cisco DevNet portal: https://developer.cisco.com/docs/nexus-dashboard

Base URI

Refer to the tables for the base URI associated with each API. To make an API request, combine the base URI with the specific endpoint path from the API reference documentation. For example, if the base URL is https://{nd-node-ip}/api/v1/manage and the endpoint is /fabrics, the full URL is https://{nd-node-ip}/api/v1/manage/fabrics.

Early Access APIs

General Availability APIs

Note: Replace {nd-node-ip} with your Nexus Dashboard domain or IP address.

Example

The full URI includes the base URI plus the endpoint listed in the API reference:

https://<nd-node-ip>/api/v1/manage/api/v1/manage/fabrics

Using Nexus Dashboard to Test API

You can test all the available API calls on a live Nexus Dashboard cluster directly from the API reference documentation page.

1. Log in to your Nexus Dashboard cluster.

2. From the top menu bar, select Help > Help Center.

3. In the Nexus Dashboard help center page, click API Reference: Swagger (in-product).

4. In the API DOCS page, use the Try It functionality to test the call.

   The following example shows how to get get the information about the user roles assigned to the current user:

   

   a) In the left sidebar, select category to narrow the list of API.

   For example, Infra.

   b) Scroll down and click on the specific API you want to test.

   c) Click Try it out.

   d) In the Parameters area, provide the payload information parameters required by the call.

   e) Click Execute to make the call.

   f) The Response area is populated with the response code and payload.

Note: In this example, there are no parameters specific to this call.

Note: In this case you can see the 200 success code and the response JSON containing the user roles assigned to your current user.

In addition to the Try It functionality, you can also use the API DOCS page to view examples of the Request and Response payloads of all available API calls.

Using Postman to Test API

Postman is an API platform for building and using API. You can use Postman to quickly and easily test API calls before you implement them in complex applications.

Installing Postman

A complete installation and configuration guide for Postman is outside the scope of this document. The following steps provide an overview of basic installation and configuration as required for use with Nexus Dashboard API testing.

1. Download and install Postman.

   You can download the installation package from https://www.postman.com.

2. Disable SSL verification in Postman.

   1. Start Postman.
   2. In the top right corner of the screen, click the tools icon and select Settings.
   3. In the General tab, disable SSL certificate verification option.

Using Postman

The following example shows how to test the login API using Postman.

1. Open Postman.

2. Create a new request.

   1. Provide the request information.

      

      

   2. Select POST and provide the URL.

      You can use the management IP address of any of the cluster’s nodes.

   3. Select how you plan to provide the request payload.

      You can select Body and raw if you want to copy and modify an existing JSON payload example, such as ones available from the API reference.

   4. Copy the JSON payload for logging in from the example in the API reference and modify it for your specific case.

      You can get sample Request and Response payloads from the complete API reference, as described in Using Nexus Dashboard To Test API.

      In this case you changed the userName and userPasswd to reflect our example.

   5. Click Send to send the request to your Nexus Dashboard.

   6. In the response payload, copy the value of the jwttoken to use for authentication in any subsequent API calls.

Using cURL to Test API

You can also use cURL to execute the calls.

1. Log in using a cURL command to retrieve the authentication token:

   curl -k --request POST 'https://<nd-node-ip>/login' \
     --data-raw '{"userName": "admin","userPasswd":"Cisco123!","domain":"DefaultAuth"}'
   

   Note: If you are running cURL from Windows, you need to escape the quotes, for example: > curl -k --request POST "https://<nd-node-ip>/login" --data-raw "{\"userName\":\"admin\",\"userPasswd\":\"Cisco123!\",\"domain\":\"DefaultAuth\"}"

   Sample response payload containing the token (jwttoken):

   {
     "jwttoken": "eyJhbGciOiJSUzI1NiIsImtpZCI6InliZTVvZjMzODFqcXphczZsZnZ5Y3c0MmlsOXZ3Ym9hIiwidHlwIjoiSldUIn0.eyJhdnBhaXIiOiJzaGVsbDpkb21haW5zPWFsbC9hZG1pbi8iLCJjbHVzdGVyIjoiNjQ2NTc2NjMtNmM3NS03Mzc0LTY1NzItMzEyZDMzMzIyZDMzIiwiZXhwIjoxNjQ0MzQzMjkzLCJpYXQiOjE2NDQzNDIwOTMsImlkIjoiNDhkMTA1YmRmYmM0OWE1ZmNmMzlhMTBiOTYxMzg2ZTYxZGZlNDAwODVjYjAzMTVkODE4Yjc2MWM1NzM1ZGFmYSIsImlzcyI6Im5kIiwiaXNzLWhvc3QiOiIxMC4zMC4xMS4zMiIsInJiYWMiOlt7ImRvbWFpbiI6ImFsbCIsInJvbGVzUiI6MTY3NzcyMTYsInJvbGVzVyI6MSwicm9sZXMiOltbImFkbWluIiwiV3JpdGVQcml2Il0sWyJhcHAtdXNlciIsIlJlYWRQcml2Il1dfV0sInNlc3Npb25pZCI6IkxIbUVVWW0zUjI3ZFNtVGRKOTdIN0lZQiIsInVzZXJmbGFncyI6MCwidXNlcmlkIjoyNTAwMiwidXNlcm5hbWUiOiJhZG1pbiIsInVzZXJ0eXBlIjoibG9jYWwifQ.JBC2b_tbE-ULqv7oQBY9I7tMI47IYDHr0loVtCD3Kd3V2TX6TGSI0W7UHtB27NxuKgVuUDa3s9CHpBlMuLe9u-RU8z6mmJAPofGmRcy33-kDq7DnFEQjcq2m41V3CPmYSYP7BrcGWi2evImGrSErkZAFWsIIcfqLJ20x8emczFFRr_Pvep0jkLtQCE6nrX1954EUvZl4Mu0WD_uQ25OdgdpRzsc1jnf2E4oWcrqoKiIah4Ai4wuVPi-NXhU5Fj8WpeX4MTjlXnQB3WKE5-3e-MyVQU_TgIAzqMs6h_dlJ9jyrhBDunXgigG1ztUY98dM39qQ6CImZVel9M3-sUrzSg",
     "username": "admin",
     "usertype": "local",
     "rbac": "[{\"domain\":\"all\",\"rolesR\":16777216,\"rolesW\":1,\"roles\":[[\"admin\",\"WritePriv\"],[\"app-user\",\"ReadPriv\"]]}]",
     "statusCode": 200,
     "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InliZTVvZjMzODFqcXphczZsZnZ5Y3c0MmlsOXZ3Ym9hIiwidHlwIjoiSldUIn0.eyJhdnBhaXIiOiJzaGVsbDpkb21haW5zPWFsbC9hZG1pbi8iLCJjbHVzdGVyIjoiNjQ2NTc2NjMtNmM3NS03Mzc0LTY1NzItMzEyZDMzMzIyZDMzIiwiZXhwIjoxNjQ0MzQzMjkzLCJpYXQiOjE2NDQzNDIwOTMsImlkIjoiNDhkMTA1YmRmYmM0OWE1ZmNmMzlhMTBiOTYxMzg2ZTYxZGZlNDAwODVjYjAzMTVkODE4Yjc2MWM1NzM1ZGFmYSIsImlzcyI6Im5kIiwiaXNzLWhvc3QiOiIxMC4zMC4xMS4zMiIsInJiYWMiOlt7ImRvbWFpbiI6ImFsbCIsInJvbGVzUiI6MTY3NzcyMTYsInJvbGVzVyI6MSwicm9sZXMiOltbImFkbWluIiwiV3JpdGVQcml2Il0sWyJhcHAtdXNlciIsIlJlYWRQcml2Il1dfV0sInNlc3Npb25pZCI6IkxIbUVVWW0zUjI3ZFNtVGRKOTdIN0lZQiIsInVzZXJmbGFncyI6MCwidXNlcmlkIjoyNTAwMiwidXNlcm5hbWUiOiJhZG1pbiIsInVzZXJ0eXBlIjoibG9jYWwifQ.JBC2b_tbE-ULqv7oQBY9I7tMI47IYDHr0loVtCD3Kd3V2TX6TGSI0W7UHtB27NxuKgVuUDa3s9CHpBlMuLe9u-RU8z6mmJAPofGmRcy33-kDq7DnFEQjcq2m41V3CPmYSYP7BrcGWi2evImGrSErkZAFWsIIcfqLJ20x8emczFFRr_Pvep0jkLtQCE6nrX1954EUvZl4Mu0WD_uQ25OdgdpRzsc1jnf2E4oWcrqoKiIah4Ai4wuVPi-NXhU5Fj8WpeX4MTjlXnQB3WKE5-3e-MyVQU_TgIAzqMs6h_dlJ9jyrhBDunXgigG1ztUY98dM39qQ6CImZVel9M3-sUrzSg"
   }
   

2. Extract the authentication token from the response payload.

   The standard login response payload contains the authentication token as well as the user's login information and role-based access control (RBAC) privileges.

   You will need to use only the authentication token for the subsequent calls.

   Optionally, you can extract the token into a shell variable to simplify future calls, for example:

   export AUTH_TOKEN=eyJhbGciOiJSUzI1NiIsImtpZCI6InliZTVvZjMzODFqcXphczZsZnZ5Y3c0MmlsOXZ3Ym9hIiwidHlwIjoiSldUIn0.eyJhdnBhaXIiOiJzaGVsbDpkb21haW5zPWFsbC9hZG1pbi8iLCJjbHVzdGVyIjoiNjQ2NTc2NjMtNmM3NS03Mzc0LTY1NzItMzEyZDMzMzIyZDMzIiwiZXhwIjoxNjQ0MzQzMjkzLCJpYXQiOjE2NDQzNDIwOTMsImlkIjoiNDhkMTA1YmRmYmM0OWE1ZmNmMzlhMTBiOTYxMzg2ZTYxZGZlNDAwODVjYjAzMTVkODE4Yjc2MWM1NzM1ZGFmYSIsImlzcyI6Im5kIiwiaXNzLWhvc3QiOiIxMC4zMC4xMS4zMiIsInJiYWMiOlt7ImRvbWFpbiI6ImFsbCIsInJvbGVzUiI6MTY3NzcyMTYsInJvbGVzVyI6MSwicm9sZXMiOltbImFkbWluIiwiV3JpdGVQcml2Il0sWyJhcHAtdXNlciIsIlJlYWRQcml2Il1dfV0sInNlc3Npb25pZCI6IkxIbUVVWW0zUjI3ZFNtVGRKOTdIN0lZQiIsInVzZXJmbGFncyI6MCwidXNlcmlkIjoyNTAwMiwidXNlcm5hbWUiOiJhZG1pbiIsInVzZXJ0eXBlIjoibG9jYWwifQ.JBC2b_tbE-ULqv7oQBY9I7tMI47IYDHr0loVtCD3Kd3V2TX6TGSI0W7UHtB27NxuKgVuUDa3s9CHpBlMuLe9u-RU8z6mmJAPofGmRcy33-kDq7DnFEQjcq2m41V3CPmYSYP7BrcGWi2evImGrSErkZAFWsIIcfqLJ20x8emczFFRr_Pvep0jkLtQCE6nrX1954EUvZl4Mu0WD_uQ25OdgdpRzsc1jnf2E4oWcrqoKiIah4Ai4wuVPi-NXhU5Fj8WpeX4MTjlXnQB3WKE5-3e-MyVQU_TgIAzqMs6h_dlJ9jyrhBDunXgigG1ztUY98dM39qQ6CImZVel9M3-sUrzSg
   

3. Use the authentication token for a service-specific API call.

   The following example shows how to retrieve the list of all sites from the Nexus Dashboard Orchestrator service:

   curl --insecure --request GET 'https://<nd-node-ip>/api/v1/manage/fabrics'\
   --header 'Cookie: AuthCookie=eyJhbGciOiJSUzI1NiIsImtpZCI6InliZTVvZjMzODFqcXphczZsZnZ5Y3c0MmlsOXZ3Ym9hIiwidHlwIjoiSldUIn0.eyJhdnBhaXIiOiJzaGVsbDpkb21haW5zPWFsbC9hZG1pbi8iLCJjbHVzdGVyIjoiNjQ2NTc2NjMtNmM3NS03Mzc0LTY1NzItMzEyZDMzMzIyZDMzIiwiZXhwIjoxNjQ0MzQzMjYzLCJpYXQiOjE2NDQzNDIwNjMsImlkIjoiNDhkMTA1YmRmYmM0OWE1ZmNmMzlhMTBiOTYxMzg2ZTYxZGZlNDAwODVjYjAzMTVkODE4Yjc2MWM1NzM1ZGFmYSIsImlzcyI6Im5kIiwiaXNzLWhvc3QiOiIxMC4zMC4xMS4zMiIsInJiYWMiOlt7ImRvbWFpbiI6ImFsbCIsInJvbGVzUiI6MTY3NzcyMTYsInJvbGVzVyI6MSwicm9sZXMiOltbImFkbWluIiwiV3JpdGVQcml2Il0sWyJhcHAtdXNlciIsIlJlYWRQcml2Il1dfV0sInNlc3Npb25pZCI6IlNKTVhQTXpiMWNNRHVTNjBaUmUzR0NDRSIsInVzZXJmbGFncyI6MCwidXNlcmlkIjoyNTAwMiwidXNlcm5hbWUiOiJhZG1pbiIsInVzZXJ0eXBlIjoibG9jYWwifQ.TbGc5Wz9-16WIH6UChYEfplRie9v_n4LrTpOthx2Mepl0FIseTkQwJGAzaBIsIjJ1dIWXjayXzVtHNURe2LHdwFIHZ9lkWGfsvh6xsrBWWerZDYuV4nsF9J0hW-LuTsnZCQxyPwL99G1SVcBKgDsnpblqkOi68cbkjED-C1ecG2WBgG3xFnjE7fQbI0Sr1y61q4FNhdkq9CBhs9jXHM4NCHDRFO8nqug67LsSJ9A-VLZXXxGJ4M9IejJkff76uz14YRoqbzgLQzvhmNkrxAqcbFm_LENV48T-2XJzcFqO7GMddmWqKxx0h4cTYps7umT63Qcnwp80rMa_7GWBsSFrw'
   

   Or the same call using the token shell variable:

   curl --insecure --request GET 'https://<nd-node-ip>/api/v1/manage/fabrics'\
   --header ‘Cookie: AuthCookie="$AUTH_TOKEN"'
   

   Response output:

   {"fabrics":[{"alertSuspend":"disabled","category":"fabric","externalStreamingSettings":{"email":[],"messageBus":[],"syslog":{"collectionSettings":{"anomalies":[]},"facility":"","servers":[]}},"licenseTier":"essentials","location":{"latitude":0,"longitude":0},"management":{"type":"vxlanIbgp","netflowSettings":{"netflow":false},"vpcLayer3PeerRouter":true,"ptp":false,"l3VniRange":"50000-59000","securityGroupTag":false,"advertisePhysicalIp":false,"fabricVpcQosPolicyName":"spine_qos_for_fabric_vpc_peering","bfdPim":false,"underlayIpv6":false,"bfdIsis":false,"nveHoldDownTimer":180,"autoUniqueVrfLiteIpPrefix":false,"ospfAuthentication":false,"macsec":false,"defaultQueuingPolicyOther":"queuing_policy_default_other","autoBgpNeighborDescription":true,"mplsIsisAreaNumber":"0001","ipv6LinkLocal":true,"autoSymmetricVrfLite":false,"policyBasedRouting":false,"vrfLiteSubnetTargetMask":30,"tenantRoutedMulticastIpv6":false,"vpcPeerLinkPortChannelId":"500","isisAuthentication":false,"perVrfLoopbackAutoProvision":false,"replicationMode":"multicast","anycastRendezvousPointIpRange":"10.251.251.0/24","vpcIpv6NeighborDiscoverySync":true,"tcamAllocation":true,"realTimeInterfaceStatisticsCollection":false,"serviceNetworkVlanRange":"3000-3199","isisLevel":"level-2","targetSubnetMask":31,"autoSymmetricDefaultVrf":false,"defaultQueuingPolicyRSeries":"queuing_policy_default_r_series","brownfieldNetworkNameFormat":"Auto_Net_VNI$$VNI$$_VLAN$$VLAN_ID$$","fabricVpcDomainId":false,"vrfLiteSubnetRange":"10.33.0.0/16","nxapi":true,"vrfLiteAutoConfig":"manual","greenfieldDebugFlag":"enable","vrfVlanRange":"2000-2299","vpcTorDelayRestoreTimer":30,"objectTrackingNumberRange":"100-299","pimHelloAuthentication":false,"bfdAuthentication":false,"bgpLoopbackId":0,"nveLoopbackIpRange":"10.111.100.0/22","vpcPeerKeepAliveOption":"management","autoVrfLiteDefaultVrf":false,"aimlQos":false,"ipv6SubnetTargetMask":126,"strictConfigComplianceMode":false,"brownfieldSkipOverlayNetworkAttachments":false,"vpcPeerLinkVlan":"3600","nxapiHttpPort":80,"bgpAuthentication":false,"leafTorIdRange":false,"rendezvousPointMode":"asm","bfdOspf":false,"bgpLoopbackIpRange":"10.11.0.0/22","aaa":false,"ntpServerCollection":["10.81.254.131"],"overlayMode":"cli","autoGenerateMulticastGroupAddress":false,"stpRootOption":"unmanaged","perVrfLoopbackAutoProvisionIpv6":false,"localDhcpServer":false,"bgpAuthenticationKeyType":"3des","siteId":"65999","bgpAsn":"65999","nextGenerationOAM":true,"cdp":false,"l3VniNoVlanDefaultOption":false,"vrfLiteMacsec":false,"vrfExtensionTemplate":"Default_VRF_Extension_Universal","tenantRoutedMulticast":false,"nxapiHttp":false,"routeMapSequenceNumberRange":"1-65534","networkVlanRange":"2300-2999","staticUnderlayIpAllocation":false,"heartbeatInterval":190,"mplsHandoff":false,"bootstrapSubnetCollection":[],"powerRedundancyMode":"redundant","bfd":false,"anycastGatewayMac":"1234.5678.9000","ntpServerVrfCollection":["management"],"vrfRouteImportIdReallocation":false,"linkStateRoutingTag":"UNDERLAY","rendezvousPointLoopbackId":250,"aimlQosPolicy":"400G","ngoamSouthBoundLoopDetect":false,"linkStateRoutingProtocol":"ospf","networkExtensionTemplate":"Default_Network_Extension_Universal","dnsCollection":["10.0.249.16"],"vrfLiteIpv6SubnetRange":"fd00::a33:0/112","fabricMtu":9216,"vpcDomainIdRange":"1-1000","hostInterfaceAdminState":true,"bfdIbgp":false,"vpcAutoRecoveryTimer":360,"dnsVrfCollection":["management"],"isisAreaNumber":"0001","snmpTrap":true,"subInterfaceDot1qRange":"2-511","privateVlan":false,"networkTemplate":"Default_Network_Universal","defaultQueuingPolicy":false,"allowVlanOnLeafTorPairing":"none","vrfLiteIpv6SubnetTargetMask":126,"anycastBorderGatewayAdvertisePhysicalIp":false,"rendezvousPointCount":2,"name":"tme-fabric","performanceMonitoring":false,"nveLoopbackId":1,"vpcDelayRestoreTimer":150,"nxapiHttpsPort":443,"vpcPeerLinkEnableNativeVlan":false,"l2HostInterfaceMtu":9216,"coppPolicy":"strict","day0Bootstrap":false,"advertisePhysicalIpOnBorder":true,"vrfTemplate":"Default_VRF_Universal","ospfAreaId":"0.0.0.0","tenantDhcp":true,"routeReflectorCount":2,"inbandManagement":false,"underlayMulticastGroupAddressLimit":128,"ipServiceLevelAgreementIdRange":"10000-19999","intraFabricSubnetRange":"10.1.0.0/16","defaultQueuingPolicyCloudscale":"queuing_policy_default_8q_cloudscale","multicastGroupSubnet":"239.1.1.0/25","fabricInterfaceType":"p2p","fabricVpcQos":false,"advancedSshOption":false,"l2VniRange":"30000-49000"},"name":"tme-fabric","securityDomain":"all","telemetryCollection":false}]}
   

Troubleshooting

A successful API call returns the 200 status code. If the response payload contains a status code other than 200, it typically also includes an error message to indicate a specific issue. In addition to the error message, you can check the following:

• Verify that you selected the correct action (for example, POST) for the specific API you are using.

• Check that the URL you provided is the same URL that you use to log into the Nexus Dashboard GUI.

• Ensure that SSL certificate verification is disabled in Postman settings.

• Check the Nexus Dashboard cluster health using the GUI or acs health command to verify there are no issues with the cluster that could prevent you from using the API.