cancel
Showing results for 
Search instead for 
Did you mean: 
cancel

Look No Code... learning about APIC-EM API without writing code...

2031
Views
19
Helpful
6
Comments
Cisco Employee

If you do not have a programming background, it might be a bit daunting to get started with REST API. Fortunately there are tools that allow you to and use REST API without needing to write a line of python.  My favourite  REST client is POSTMAN.

This blog provides instructions for downloading a POSTMAN collection for APIC-EM sandbox controller.

The collection has samples for many common API calls.  In addition it uses some of the awesome POSTMAN features to pre-populate variables, so you do not have to cut/paste information between calls that are linked.

Getting Postman

You can download POSTMAN from https://www.getpostman.com/   You do not need to create an account, and it is free to use.

Importing the Collection

Once you open postman, you will need to import the two files below

https://raw.githubusercontent.com/CiscoDevNet/apic-em-samples-aradford/master/tools/postman/APIC-EM%2520Sandbox.postman_collection

https://raw.githubusercontent.com/CiscoDevNet/apic-em-samples-aradford/master/tools/postman/APIC-EM%2520Sandbox.postman_environment

First click on "Import",

Then "Import from Link",

Then paste the URL into the box as shown.

Press "Import". NOTE:  You need to do this for both files.

import.png

Getting Started - Authentication

After the two steps above you should have the collection and the environment successfully imported into POSTMAN.   The next step is to get an authentication token, as all API calls on APIC-EM are authenticated.

You need to open the folder in the collection called "1. Ticket" and then press "SEND" on the right hand side.  The body off the call is using two variables "{{username}}" and "{{password}}".  These come from the environment variables that you downloaded.  You will notice that the APIC call itself also has environment variables for the {{apic}} and the {{port}} that it is listening on. 

auth.png

You should see a response similar to the following.  The "serviceTicket" contains the token that will be required for all subsequent API calls.  The timeouts are in seconds.  The idle timeout for this ticket is 30mins.

service ticket.png

To make life easier, the value of the ticket has been automatically collected and saved in an environment variable called "ticket".  If you click on the icon to the right of the "APIC-EM Sandbox", you will see all of the variables (and their values).  Notice how the token variable has been populated.

variables.png

If you open the "2. network-device" folder and click on the first API call, then on "headers" you will see that the "x-auth-token" header is set to the variable "{{header}}".  This will be changed dynamically each time you POST the "/api/v1/ticket" request.  Note: a ticket is valid for 6 hours in this example

token-header.png

Linking API Calls

As seen in the https://communities.cisco.com/community/developer/dna/blog/2017/02/20/top5-api-for-apic-em-engineer-productivity-part5 blog, some API calls need to be linked together.  Data from the output of one call, needs to be used as a parameter to the next.

Open the "4. Path Trace" folder and the first call to setup a Path Trace.  This API call requires a source and destination IP address. Press "Send".

PT-post.png

The result is a Task. The ID of the task is return and also saved in a variable in the environment in the top right hand corner.

task.png

This will be used in the next call, which will show the output of the task.  The GET of "/task/{{taskId}}" show the output of the task.  The value in the "progress" field is the path trace result obtained in the next API call.

task-response.png

Select the "flow-analysis/{{pathId}}" call, and run that.  You will now get the result of the path trace.

path-trace.png

Without the variables, you would need to cut and paste the token, the "pathId" and the "flowId" from call to call.

What is the Trick?

Go back to the "/api/v1/ticket" API call.  Click on "Tests".  There is some javascript that runs after the API call, that collects the token from the reponse and saves it in an environment variable.

trick.png

Other API calls that need to collect data will use a similar approach.  This is how the environment variables are populated.

What Next?

This blog will get you started with REST API calls to an APIC-EM controller in the cloud.  You can change the environment variables to point to your own controller.

Take a look at my blog index for other related topics. https://communities.cisco.com/people/aradford/blog/2016/11

In the meantime, if you would like to learn more about APIC-EM, you could visit Cisco Devnet.  All of the code samples can be found in this Github repository.

Thanks for reading

@adamradford123

6 Comments
Beginner

Hi ,

I am getting below error when sending 1.ticket query using postman app. What can be the reason for this?

Could not get any response

There was an error connecting to https://%7B%7Bapic%7D%7D:%7B%7Bport%7D%7D/api/v1/ticket.

Cisco Employee

Hi,

you need to select an environment for postman.  The environment contains the variables required.

Beginner

Thanks Aradford!

After selecting environment that error is gone . But still I am not able to connect to sandbox apic server . I tried to disable anti virus and other stuff but it didnt work .

Could not get any response

There was an error connecting to https://sandboxapic.cisco.com:443/api/v1/ticket.

Why this might have happened:

  • The server couldn't send a response:Ensure that the backend is working properly

  • Self-signed SSL certificates are being blocked:Fix this by turning off 'SSL certificate verification' in Settings > General

  • Proxy configured incorrectlyEnsure that proxy is configured correctly in Settings > Proxy

  • Request timeout:Change request timeout in Settings > General

Cisco Employee

postman.jpg

Turn SSL off from Postman preferences

Beginner

Thanks Yawchen ! It is so silly , I didn't notice to check postman app

settings rather I was checking my computer settings.

Thanks !

Beginner

Excellent!!!

Content for Community-Ad
August's Community Spotlight Awards
This widget could not be displayed.