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.
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.
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:
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:
Then you have to create the three variables:
Insert three values to go with the three key variables from above into the Initial Value column:
Select and activate your aci-env Environment in the Environment dropdown box.
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.
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:
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.
POST
In the request editor,
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}}"
}
}
}
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.
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.
Then you are going to:
GET
.
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
And see the results the the APIC sent in reponse that are the list of all fabric switches, past and present of this fabric.
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.
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:
GET
.
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.