Postman
Used by many developers!

Postman is a powerful GUI client designed to mainly test API development by building API requests within the client framework. Postman is an application that is available across platforms, including Windos, macOS and Linux. In this lab, we will be leveraging the native Postman app , which has already been installed for you. If you wish to install Postman on your personal machine, simply from the internet on their website http://www.postman.com.

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:

  1. Clicking Collections, then the + plus icon
  2. In the popup tab, name your collection aci-lab
  3. Then hit Enter (or Return) on your keyboard
Feel free to reference the image below for the steps.

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.

You create your own Environment by:

  1. Clicking Environments
  2. Clicking + plus icon
  3. In the popup tab, name the environment aci_env
  4. Then hit Enter (or Return) on your keyboard
Feel free to reference the image below for the steps.

Then you have to create the three variables:

  • apic
  • username
  • password

Insert three values to go with the three key variables from above into the Initial Value column:

  • apic: 10.0.226.41
  • username: aciproglab04
  • password: cisco.123
Click Save when complete

Select and activate your aci-env 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:

  1. Click on Collections again
  2. In your aci-lab Collection, click the 3-dots
  3. In the dropdown menu, click Add request

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.

  1. Name the request as APIC Login
  2. Add the destination URL: https://{{apic}}/api/aaaLogin.json
  3. Change the request type to POST

In the request editor,

  1. Click Body
  2. Click raw
  3. 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. 


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

  1. Insert ths data structure into the Body of your request
  2. Then click Save

Step 6 - Run Authentication Request

To send the ReST request to the APIC press the Send button.

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.

Step 7 - Send Query Request Fabric Devices

In the previous chapter we used the example of requesting the list of fabric switches. The URL that we used for this example was: http://10.0.226.41/api/node/class/dhcpClient.json . For this part of the lab we are going to now do this request directly with POSTMAN. Just like you did for the authentication request, you will start with creating a new request.

  1. Click on Collections again
  2. In your aci-lab Collection, click the 3-dots
  3. In the dropdown menu, click Add request

Then you are going to:

  1. Name it Fabric Switches
  2. Add the destination URL: https://{{apic}}/api/node/class/dhcpClient.json
  3. The request type is going to be GET.
  4. Click Save

Depending on how long it took you to go through these steps you might have had a token timeout and you will have to run the APIC Login Request before running this request. By the default the Token timeout is set to 300 seconds. So run the APIC Login Request first.

And now you should be able to run the Fabric Switches request

  1. Ensure you have the Fabric Switches request open
  2. Click Send
  3. Check for status 200 OK and response

And see the results the the APIC sent in reponse that are the list of all fabric switches, past and present of this fabric.

Step 8 - Send Query Request to APIC for Fabric Endpoints

Lets take this fun experiment in a different direction. A more useful tool for the network engineer is to know what fabric endpoints are in the network. Since the ACI fabric acts as a single network entity ( think of ACI as the spines being the backplane and the leafs are the line-cards). The URL that you will be using to get this data is: 


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

To accomplish this you will need to first create a new request.

  1. Click on Collections again
  2. In your aci-lab Collection, click the 3-dots
  3. In the dropdown menu, click Add request

And this request is going to bet a GET request as we are only asking the APIC to send us back the list of devices.

Then you are going to:

  1. Name it Endpoints
  2. Add the destination URL: https://{{apic}}/api/node/class/fvCEp.json
  3. The request type is going to be GET.
  4. Save

Depending on how long it took you to go through these steps you might have had a token timeout and you will have to run the APIC Login Request before running this request. So run the APIC Login Request first.

And now you should be able to run the Endpoints request. Upon completion you will have a list of all the endpoints that the ACI fabric has learned.

For the many aspects of the lab we are going to play with the fvCEp object structure. So you will be doing work in the lab from a simple Python script to a complete web application on this particular object.