Using Postman to talk REST to ACI

Before jumping into using Python and with now having a basic understanding of ACI's REST structure, lets take a look at what has become a common tool for interacting with network platform and controller REST APIs - Postman.

What is Postman?

Postman is a powerful GUI client designed to mainly test API development by building API requests within the client framework. The Postman application is avaialble in two forms; as the Google Chrome app plugin/extension or as a native app for Mac, Windows, or Linux. In this lab, we will be leveraging the native Postman app for Linux, which has already been installed for you. If you wish to install Postman on your personal machine, simply download the Mac zipfile or Windows executable. Since the Linux Postman app is still beta, after you download the tar.gz file, it takes a few manual steps to install that you can find in the References section.

Step 1 - Launch Postman

You will be presented with the Postman GUI client. The left side of the GUI is called the sidebar while the center and main screen is considered the request editor.

Step 2 - Create Collection

The first thing you want to do is create your own Collection. In the sidebar, click Collections. You will notice that Postman has a default Collection, but this is unrelated to ACI. You create your own Collection by clicking the folder icon. In the popup window, name your collection aci-lab and then click Create as shown in the image below:

Step 3 - Create Environment

With a Collection in place to store your requests you will next need to create a Postman Environment. The Environment within Postman allows you to create key/value pair mappings for things that you would like to make into variables to be used over and over easily. You are going to create variables and subsequent key/value pair mappings for the APIC IP Address, your username, and your password for the APIC.

Click the gear to the far right and then click Manage Environments in the dropdown menu.

Within the Manage Environments popup window, click the BIG orange Add button to add a new Environment.

Create an aci-env as show below. Insert three key/value pairs: apic:10.0.226.41, username:aciproglab03, and password:cisco.123. Click Add when complete.

With your Environment created, close the Manage Environments popup window by clicking the 'X' at the top right.

Select and activate your Environment in the Environment dropdown box.

Step 4 - Disable SSL Certificate Verification

The APIC controller by default installs a self-signed certificate. To be able to interact with a self-signed certificate, you have to either disable the warnings or tell the client that is interacting with the device to accept that certificate as valid. There are various ways to accomplish this goal and in POSTMAN you will simply tell it to ignore the validation for simplicity purposes.

We're going to ignore the self signed certificate that is on the APIC controller for the purposes of this lab. To do so, click the wrench icon and in the dropdown box, click Settings.

In the Settings popup window, click the SSL certificate verification to off. Click the 'X' at the top right to close the Settings popup window.

Step 5 - Create Authentication Request to an APIC

You're now going to create your first request to the APIC to obtain an authentication token. This request will be a POST using the Universal Resource Identifier (URI) aaaLogin as the Distinguished Name (DN). The payload for the this request is composed of the Managed Object (MO) aaaUser. The aaaUser MO contains attributes for the username and password as name and pwd respectively. The response from this request will contain an authentication token from the APIC that includes a Set-Cookie header and a token for the aaaLogin object that can be used by future requests to authenticate.

In Postman, click your newly created Collection. In the request type, select POST. Using the ACI REST syntax discussed in the previous section (and above for convenience), the REST URL can be determined as below. Insert this URL as the REST POST URL into your Postman app using the apic environment global variable as the APIC IP address will be resolved using your Postman Environment.


https://{{apic}}/api/aaaLogin.json

In the request editor, click Body, then click raw, and in the dropdown that says Text, select JSON. Below is the JSON data structure that is used in the user login message to obtain a token. You can see that the name and pwd keys will utilize your username and password environment variables. Insert ths data structure into the Body of your Postman app. Once your Postman app looks like the below image, click the Send button to perform the REST call.


{
    "aaaUser" : {
        "attributes" : {
            "name" : "{{username}}",
            "pwd" : "{{password}}"
        }
    }
}

Upon a successful POST, you will get a response from the APIC with a 200 OK and a return payload that contains the authentication token. This token is valid for 300 seconds or 5 minutes. There are additional DNs for refreshing the token, aaaRefresh, or logging out the session, aaaLogout.

You can examine the Cookie returned back from the APIC as part of the authentication request. In the return, it is called APIC-cookie. You will see this again later in the Pyton and Javascript sections of the lab. This cookie can now be used to make subsequent requests to the APIC.

You can also examine the Header returned from the APIC. You can see the cookie here as well.

Step 6 - Save Request into Collection

Up to this point, you have created a POST REST call, but it hasn't been saved. Click the Save button to save this login request and add it to your Collection repository. In the popup window, name the request apicLogin, select your aci-lab Collection in the collection/folder, and click the orange Save button.

Step 7 - Send Query Request to APIC for Endpoints

We're going to continue using the same example from the previous section, End Points. Using the fvCEp class found previously, you're going to issue a remote request to query the APIC for all the end points in the fabric, much like we saved these end points directly from the APIC GUI to learn the class. Click the plus (+) to create a new request window, which should default to using a GET request. Insert the request call into the GET request URL field. Again, we've already authenticated in the previous section and this request will make use of the apic environment global variable in the request URL. Click Send to get a response with all the end points in the fabric.


https://{{apic}}/api/node/class/fvCEp.json

Step 8 - Save Query Request into Collection

Just as you did for your authentication request, click the Save button to save this query into your Collection. In the popup window, name the request fvCEP, select your aci-lab Collection in the collection/folder, and click the orange Save button.

In your Collections pane, you should now have a POST and a GET request in your folder.

So let's go into the lab and do the exact same operation with the request library in Python.