Manage Cisco ACI with Postman

What is Postman?

Postman is third party REST API tool. This can be used to create and retrieve object information in ACI.

Postman for Cisco ACI as a REST API

Cisco ACI is built with an API first approach, everything you see and do in the GUI is an API call in the end. The GUI is just another API client itself!

Postman also is just another API client allows for easy API Calls to Cisco ACI, Like a browser when you mange you ACI fabric via GUI interface the Postman is just another API client itself to get or Post a configuration to ACI managed objects.

Postman can be used to push configuration to the APIC via the Restful interface quicker and more flexible than what can be accomplished if we did the same configuration via the GUI.

What is ACI Distinguish Name and Managed Object?

In ACI the components like (VRF, AP, EPG, Contract, ..) are represented in a management information tree (MIT). Each component in MIT is a managed object (MO). MOs are identified by unique distinguished name (DN). This DN provides the fully qualified path (URL) from the root of the object tree to the object itself.

How to use Postman with Cisco ACI?

• First you need to grab Postman on your PC and start to mange ACI fabric through Postman.

To download Postman :

https://www.getpostman.com/

• Once you are welcomed by this screen, you will have the below workflow :

• Postman Terminology :

a. Collections : Container of API requests.

b. API Request : This is the API request you will create to do any action and manage ACI fabric.

1. Request Type : such as Post to write object OR Get to read object.

2. URL : This identified by DN which represent distinguished name for the object you need to configure.

3. Body : This represent by JSON code will deploy this object/s.

c. Environment : Environment tab represent a predefined variables so you can create Environment per customer if you are managing multiple customers.

Workflow :

1. Define you variables by Environments which means each Environment represented a Customer.

Note : variables used to reuse values in multiple requests and protect sensitive data,

for example : you can create variables for APIC username, password and Tenant name so that you can reuse them in multiple API requests.

So, you can see in above shots I've created variables will be reused in many tasks such as APIC username & pwd and Tenant name.

2. Create a Collections which represent Container of API requests such as (Login Request , create Tenant, create EPGs, BDs,...).

You can see in the above shot I've created a new collection and gave it name.

3. Now, you can start to create your own tasks which called a request in postman dashboard, for example (Login request, Create EPG/EPGs, VRFs, BDs,...)

As discussed in our intro, any request has main 3 components :

a. Request Type : such as Post to write object OR Get to read object.

b. URL : This identified by DN (object path in MIT tree) which represent distinguished name for the object you need to configure.

c. Body : This represent by JSON code will deploy this object/s.

As you can see I will add a new request to any task such as Login to APIC or create EPG ..)

Let's take some Examples to create simple API request and understand workflow :

1. Create Login API Request :

Name : Login

type : POST

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

Body :

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

Explanation :

in the above example I've created a new request with name : login

adding URL in object model and type will be POST which means do action and finally add JSON code which will do the needed action.

Notice that I put apic username and password in between {{apicusername}} as I already created variable named apicusername so once I run the script it will retrieve the predefined values match variable name automatically.

2. create the new tenant with the name "Customer-1"

type : POST

URL : https://{{apic}}/api/node/mo/uni/tn-Customer-1.json

Body :

{"fvTenant":{"attributes":{"dn":"uni/tn-Customer-1","name":"Customer-1","rn":"tn-Customer-1","status":"created"},"children":[]}}

====================================================

Okay great but the question is how we can get the JSON code (request body) to create any object or multiple objects with simple way without manually write a code?

Answer : Via APIC API inspector.

This is the simple way on how to find the ACI Object code and it's URL in MIT tree.

Let's assume that we need to create EPG with POSTMAN so as discussed we need to add new API request creating EPG including main components (name, Type, URL and Body) so how we can get URL and Body?

3. Create EPG and Learn how to find ACI EPG Object code.

1. Open the API Inspector.

On the top right of your APIC, click Settings > Show API Inspector

Once you click this, the pop-up window display API Inspector showing JSON code and URL.

2. Create a sample EPG under the Application Profile (AP).

In this example, we're creating EPG sample with the BD sample.

3. Using the API Inspector we search on POST command to find the method.

Here we can find the method, the content of the url and the payload.

4. Once you extracted the information (URL & Code) from the API Inspector, you can copy and paste it to your Postman and then edit name as you like.

So, I will copy the URL and body and edit EPG name.

type : POST

URL : https://{{apic}}/api/node/mo/uni/tn-customer-1/ap-Production-ap/epg-EPG-Database.json

Body :

{

"fvAEPg": {

"attributes": {

"dn": "uni/tn-customer-1/ap-Production-ap/epg-EPG-Database",

"name": "EPG-Database",

"rn": "epg-EPG-Database",

"status": "created"

},

"children": [{

"fvRsBd": {

"attributes": {

"tnFvBDName": "BD-sample",

"status": "created,modified"

},

"children": []

}

}]

}

}

Now I've create API request adding new EPG with name EPG-Database associated to BD : BD-sample

====================================================

So till now we've discussed the concept of using POSTMAN to manage ACI, POSTMAN terminology, workflow, and how to create API request with example.

Now, Let's move on more advanced options to automate ACI configuration.

So Let's discuss how to create a multiple object in a single API request.

Let's start with very simple example that I need to create 10 EPG associated with different BDs in single API request.

4. ACI Automation - Configuring Multiple EPG :

In order to create multiple EPGs, we’re going to use spreadsheet.

The spreadsheet is a simple CSV file that can be created from Microsoft Excel which will include our objects will be created.

1. Create EPG Spreadsheet

Remember, we discussed the Postman variables earlier.

Simple I've created excel sheet included 10 EPG with 10 BDs,

remember that we will use variables "EpgName" & "bdName" in our code so that it will be called from spreadsheet once run the script and attach CVS file.

2. Once you create this table in your Excel spreadsheet, you can save this as .CSV.

3. Create API requested with variables :

As discussed before we will get EPG code (URL & Body) via API inspector then replace EPG and BD names with variables names in our spreadsheet created before as below example :

type : POST

URL : https://{{apic}}/api/node/mo/uni/tn-customer-1/ap-Production-ap/epg-{{EpgName}}.json

Body :

{

"fvAEPg": {

"attributes": {

"dn": "uni/tn-customer-1/ap-Production-ap/epg-{{EpgName}}",

"name": "{{EpgName}}",

"rn": "epg-{{EpgName}}",

"status": "created"

},

"children": [{

"fvRsBd": {

"attributes": {

"tnFvBDName": "{{BdName}}",

"status": "created,modified"

},

"children": []

}

}]

}

}

Explanation :

In the above example I've created a spreadsheet and put variable name "EpgName" and "BdName" in the sheet then added 10 EPG names and replaced EPG name and BD name in the JSON code with variables will be retrieved from excel sheet so that after run the code it will do the request 10 times with each EPG name then associate it to it's BD in the sheet.

Run the script :

1. Click on Runner and choose the requests you need to run.

In my example I'll run login request and create EPG requests so it will first login to APIC and then create the EPGs associated with BDs.

2. select the CVS file you created to get the variables defined.

As you see I've attached CSV file and preview the file found the Runner detect all variables names and counter will be 10 which means it will run 10 times to create 10 EPGs.

3. Run API call and see the result.

4. Result in APIC.

Expected to see in ACI 10 EPGs created and associated to BD.

In the Next Article we will try to post more advanced examples such as creating multiple EPGs with diff. BDs and do a static port binding in single API request which will be valuable in new implementations to save time and automate process in large environments.

Thanks for reading and waiting you kind feedback or any comment .. :)