ND/NDFC API Documentation

There are several resources for understanding the APIs that power ND/NDFC. The first is the API documentation that comes embedded within ND for all services running on it. The second, you can view offline, without access to ND/NDFC and found on Cisco DevNet's website. As you will explore below, these resources can help you learn, navigate, and try out different API endpoints.

Step 1 - Navigate Back to NDFC Dashboard

In your browser, close your staging fabric.

1. Click the X (close button) in the top right

Step 2 - Access ND/NDFC Live API Documentation

Back at your NDFC main dashboard, locate Help in the top-right corner:

1. Click the Help to expand the drop-down menu
2. Click Help Center in the drop-down menu




3. In the Help Center, click REST API

Step 3 - Confirm Your Browser is at API Docs

Your browser should have opened a new tab to the ND/NDFC API Docs as shown below:

Using Live API Documentation

The APIs of ND/NDFC follow the OpenAPI 3.0 spec and the live documentation has swagger tools built-in, so users can try and test the API directly from Nexus Dashboard. Because NDFC is running as a service on Nexus Dashboard, all the authentication and authorization are provided by ND and ND provides a single API gateway for all the services running on top of it.

The Nexus Dashboard and services APIs require access via an authenticated and authorized account. Only authorized accounts are able to submit requests to API operations. All operations must communicate over a secure HTTPS connection. When you authenticate using the /login endpoint, you receive an authorization token identified by the key name jwttoken in the response from ND. This is a JSON Web Token (JWT) in response payload and cookies which you must then include in the request of each subsequent API operation in the format of a cookie.

• Key: AuthCookie
• Value: the value of jwttoken in response of /login API call

Let's examine the API documentation, and in the following sections, we'll see how to construct this request in Postman and Python.

Step 1 - Authentication and Authorization ND Login API Endpoint

To test it, in the REST API page you just opened in the browser:

1. Make sure Nexus Dashboard is selected




2. Expand the Authentication on the left sidebar
3. Click the Login endpoint
4. Ensure the Body format is set to JSON
5. Copy the following authentication payload below, then paste it in the Body section of the API login call by selecting all (the empty JSON that is there) and replacing it with what you have copied:

   
   {
       "domain": "local",
       "userName": "admin",
       "userPasswd": "cisco.123"
   }
               
               

6. Click the Run button

Step 2 - Confirm ND Login API Endpoint Response

You should get a response that looks like the screenshot below:

Testing out this request via the API Docs tells you that the request you would send to ND would be the following:

You used the POST method and the login API endpoint URL:

    POST https://10.15.0.98/login

You used the admin user account and local login domain in the POST payload to ND:

    {
        "username": "admin",
        "userpasswd": "cisco.123",
        "domain": "local"
    }

An example of the response you received is:

    {
        "jwttoken": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ijdjc3ZqYjltZDBzcTl6ODI4c2o1Nm9rcHZ3eWpuOGp3IiwidHlwIjoiSldUIn0.eyJhdnBhaXIiOiJzaGVsbDpkb21haW5zPWFsbC9hZG1pbi8iLCJjbHVzdGVyIjoiNGU0NDJkMzEtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwiZXhwIjoxNjg1MzY1NTE4LCJpYXQiOjE2ODUzNjQzMTgsImlkIjoiNDhkMTA1YmRmYmM0OWE1ZmNmMzlhMTBiOTYxMzg2ZTYxZGZlNDAwODVjYjAzMTVkODE4Yjc2MWM1NzM1ZGFmYSIsImlzcyI6Im5kIiwiaXNzLWhvc3QiOiIxMC4xNS4wLjExIiwicmJhYyI6W3siZG9tYWluIjoiYWxsIiwicm9sZXNSIjoxNjc3NzIxNiwicm9sZXNXIjoxLCJyb2xlcyI6W1siYWRtaW4iLCJXcml0ZVByaXYiXSxbImFwcC11c2VyIiwiUmVhZFByaXYiXV19XSwic2Vzc2lvbmlkIjoiWGNkYnBMcWE9TDRpRlhQbndZZHExT0UwIiwidXNlcmZsYWdzIjowLCJ1c2VyaWQiOjI1MDAyLCJ1c2VybmFtZSI6ImFkbWluIiwidXNlcnR5cGUiOiJsb2NhbCJ9.YJO9pU3tKIU64rHIx6L41fCuQaHhxIOJj7RzieE479n8zpgyVNT_FgWdKmQX6H7sKJpMqVHf9bgIQWCq-RKpUgmWey0mAiMBv7o3zUf3bZcM6nCPZk4ouf28Pw8yFgj2j_EUUlhaUPpxXAtP89d8vL4s9ZLpzDCZDWWXeAzNCKtZj6ZLEt_EGRxKXoHsObGB9x_W0iwB4OCa6NjQYMfA0cN7iV3Iwk29cF4uGhVZqbyOCjQkDpUZjaV-IFtu6VReGckviDQBiFs3PXM9-j8FOxAs4IW5Z-2NZG1U-Tdbm3bneMtKlitkXngZjXAXm9WizpIusOa32Z-pChlGQhPBDg",
        "username": "admin",
        "usertype": "local",
        "rbac": "[{\"domain\":\"all\",\"rolesR\":16777216,\"rolesW\":1,\"roles\":[[\"admin\",\"WritePriv\"],[\"app-user\",\"ReadPriv\"]]}]",
        "statusCode": 200,
        "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ijdjc3ZqYjltZDBzcTl6ODI4c2o1Nm9rcHZ3eWpuOGp3IiwidHlwIjoiSldUIn0.eyJhdnBhaXIiOiJzaGVsbDpkb21haW5zPWFsbC9hZG1pbi8iLCJjbHVzdGVyIjoiNGU0NDJkMzEtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwiZXhwIjoxNjg1MzY1NTE4LCJpYXQiOjE2ODUzNjQzMTgsImlkIjoiNDhkMTA1YmRmYmM0OWE1ZmNmMzlhMTBiOTYxMzg2ZTYxZGZlNDAwODVjYjAzMTVkODE4Yjc2MWM1NzM1ZGFmYSIsImlzcyI6Im5kIiwiaXNzLWhvc3QiOiIxMC4xNS4wLjExIiwicmJhYyI6W3siZG9tYWluIjoiYWxsIiwicm9sZXNSIjoxNjc3NzIxNiwicm9sZXNXIjoxLCJyb2xlcyI6W1siYWRtaW4iLCJXcml0ZVByaXYiXSxbImFwcC11c2VyIiwiUmVhZFByaXYiXV19XSwic2Vzc2lvbmlkIjoiWGNkYnBMcWE9TDRpRlhQbndZZHExT0UwIiwidXNlcmZsYWdzIjowLCJ1c2VyaWQiOjI1MDAyLCJ1c2VybmFtZSI6ImFkbWluIiwidXNlcnR5cGUiOiJsb2NhbCJ9.YJO9pU3tKIU64rHIx6L41fCuQaHhxIOJj7RzieE479n8zpgyVNT_FgWdKmQX6H7sKJpMqVHf9bgIQWCq-RKpUgmWey0mAiMBv7o3zUf3bZcM6nCPZk4ouf28Pw8yFgj2j_EUUlhaUPpxXAtP89d8vL4s9ZLpzDCZDWWXeAzNCKtZj6ZLEt_EGRxKXoHsObGB9x_W0iwB4OCa6NjQYMfA0cN7iV3Iwk29cF4uGhVZqbyOCjQkDpUZjaV-IFtu6VReGckviDQBiFs3PXM9-j8FOxAs4IW5Z-2NZG1U-Tdbm3bneMtKlitkXngZjXAXm9WizpIusOa32Z-pChlGQhPBDg"
    }

For subsequent API requests, the value associated with the jwttoken key will be used as the value of the AuthCookie cookie.

A Note About ND JWT Token Refresh

All JWT tokens expire after a certain period of time. Since all subsequent API calls rely on the authentication token you receive when you first login, you may want to refresh the existing token instead of obtaining a new one by logging in again.

If you wanted to refresh the token, you would send an empty payload using the POST method with the jwttoken as AuthCookie cookie to the API endpoint /refresh:

    POST https://10.15.0.98/refresh

where the jwttoken is in the request cookie as AuthCookie:

    AuthCookie: value of jwttoken

The default token duration is 20 minutes, but can be changed under the ND Admin Console. We are NOT going to update the token duration in this lab, but if you wanted to do so, you would:

1. Navigate back to ND Admin Console - https://10.15.0.98
2. Admin
3. Security
4. Update the Session Timeout

Continue to the next section to explore the NDFC API Docs.