cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
11086
Views
5
Helpful
1
Comments
Ashley Herring
Community Manager
Community Manager

By Andrew Boring

 

Let’s talk about Curl.


If you’ve spent any time with the ACI interface, you’ve probably realized that herding a mouse around a browser is fine for small/one-time operations, but does not scale when you have a large quantity of repetitive operations.


Maybe you started using Postman to run API queries, but you want to build a succession of queries and roll them up in a script. If you’re competent with Python, you might even be using the Cobra SDK or ACI Toolkit to develop anything from simple scripts to integration with other infrastructure components.


On the other hand, maybe you like pain and suffering and have a preference for simple shell scripts. If this is you, you’ll be using curl.


In this series, we’ll explore using curl on the command line and in simple shell scripts for quick, repeatable operations.


If you’re not familiar with curl, it’s an excellent utility for interacting with HTTP servers, especially for performing CRUD operations against an API. Further, you can connect to other Unix tools by using conventional STDIN/STDOUT interfaces. This can help you quickly prototype applications by connecting components to repeat frequently-used tasks.


Anatomy of a curl request.


You’ve probably used curl to download a file from a webpage, like this:

 

curl http://www.unofficialaciguide.com/index.php


This performs a simple GET request on the server, retrieving the data and printing it out on the screen.


To perform other HTTP operations (HEAD, PUT, DELETE, POST, etc), you might use the -X switch:


curl -X POST -d "some data" http://example.com/api/path/to/object


To use HTTPS when you have a self-signed certificate, maybe you’ll add the -k switch to bypass untrusted certificate warnings (useful for internal testing where a quick cert is all that’s needed):


curl -k https://example.com/api/path/to/object


If you need to pass HTTP header information, like content-type, simply add -H with the headers, like specifying XML:


curl -X POST -d "param1=value1" -H "Content-Type: application/x-www-form-urlencoded" http://example.com/api/object


or JSON:


curl -X POST -d '{"key1":"value1"} -H "Content-Type: application/json" http://example.com/api/object


When constructing requests, it will be helpful to have some reference materials handy.


First, you’ll want the official Cisco APIC REST API Configuration Guide, as that is the authoritative API reference.


Secondly, while the full curl manual page (“man curl” at your Unix/Linux prompt) is quite comprehensive, it can be challenging to find the exact switch you need among all the options available to you. A good online reference is useful. I personally find this Gist to be a good intro/quick reference for the most common curl options and usage.


Finally, parsing the XML output can be an adventure in formatting. Useful tools include json_pp and xmllint are common formatting utilities when working with raw curl output, while standard Unix tools like grep, sed, cut, etc will be indispensable.

 

In order to interact with the API, we will need to authenticate.


An authentication POST request will require a username/password, expressed using the aaaUser object. The XML version looks like this:

 

1.JPG

Substitute your username, password, and IP address/hostname as needed. The leading $ sign indicates a command prompt, and should not be typed.


The response will include a session token and a number of attributes. We can use the token to pass subsequent requests, but extracting the token programmatically can be painful when you just want to run a quick command or two.


We’ll use curl’s -c switch to save the info in a cookie file, named “COOKIE”:

 

2.JPG

Then, you simply use “-b COOKIE” in subsequent requests, such as retrieving a list of tenants:

 

3.JPG

You can pass XML output through the xmllint utility to format (indent) it:

 

4.JPG

Don’t forget that trailing hyphen! The pipe | character tells the shell to take the output of the curl command and use it as input to xmllint. The trailing hypen tells the xmllint program to read from input rather than a file.


Another way to do this is to save the output to a file, and then read the file using xmllint (or your favorite XML editor).

 

5.JPG

If you’re using JSON, you can use a tool called json_pp (“pretty print”) to get nice formatting:

 

6.JPG

We’ll dive more into using curl to interact with the APIC API in upcoming posts. But that wraps up today’s blog!


More blogs regarding ACI are yet to come right here on the ACI Board on Cisco Community. Make sure to drop a comment and let us know if this piece focused on “Curl” was helpful!


And as always, we’d love to know what other topics you’d like us to write about in future ACI blogs. Help us, help you!

1 Comment
derek.andrew
Level 1
Level 1

This is great. 

During the crises in 2020 when we all work from home, often on inadequately sized internet links, is it possible to use curl to download software from the Cisco download site? It would be so great to download software using the high speed internet links at the office instead of my little internet pipe at home.

Getting Started

Find answers to your questions by entering keywords or phrases in the Search bar above. New here? Use these resources to familiarize yourself with the community: