When you’re using curl to interact with the APIC API, or even if you’re using a toolkit/library to create applications, you may want to know which APIC API methods and objects are available for a given task.
Yeah, yeah. RTFM. You know what’s up. You’ve already done that. You’ve read the Cisco APIC REST API Configuration Guide, at least until your eyes started to blur and lose focus.
Here are a few quick ways to get the APIC API info you need for the task you’re doing right now. And you can even do it while your boss is peering over your shoulder looking slightly confused at your elite command-line skills.
APIC API Inspector
The first method is the API inspector.
Clicking on the gear sprocket in the upper-right corner provides a menu of Helpful Options. Select API Inspector to open a small window showing each API call for everything you click on in the GUI.
Want to know how to get a list of tenants?
Just turn on API Inspector, click on the Tenants menu, and watch the API calls scroll by.
Want to know what API activates/deactivates a check box option?
Just navigate to the screen, make the settings change, and submit it to get the right POST call. Change it back to confirm it (this will include some helpful POST data as well).
Some GUI screens will consist of many API calls, for example dashboard screens retrieving health status, so you’ll need to read through the calls carefully. You may wish to uncheck the box “Scroll to latest” to prevent GUI screen refreshes from scrolling additional API requests in the Inspector while you’re trying to read.
The Save As/Post
If you used the API Inspector to find the object, but are having trouble figuring out the exact POST data you need to send, the Save As option will conveniently download the configuration data in your choice of XML or JSON file. You can make the necessary changes and use POST within the GUI or via curl to test the change directly.
Right click on the object, select “Save As…”, and then select your options in the modal dialog.
Content: All Properties vs Only Configuration – Shows whether you want to retrieve just the relevant properties to a configuration, or all properties, including objects and attributes indicating relationships to other objects.
Scope: Self vs Subtree – Determines whether you want just the object itself and its attributes, or the object with attributes AND its child objects, with attributes.
Export Format: XML vs JSON – Indicates your preferred text format, eXtensible Markup Language or JavaScript Object Notation.
Normally when we are saving configuration to post back we want to select ‘Only Configuration’ since ‘All Properties’ may contain values that the APIC won’t accept when you ‘POST’ back. Subtree is often the preferred option over Self, but if you’re working with just the object-level attributes, saving just Self will work fine. You can certainly save both and compare the two.
After saving the file and editing its contents, you can use the Post option to effect the change.
Be careful with your objects though!
In the example above, we’re operating on the exact object we wish to change. In other cases, the object itself might not exist (yet), so we’d need to POST back to the parent object.
For example, the DN of a tenant object won’t exist until you actually create the tenant. So if you want to use an existing tenant configuration, you can save a tenant config, modify it for the new tenant configuration, but POST it to a new object based on your desired configuration. For example, let’s save a Tenant:
In the example above, we want to save the COAST user as tn-COAST.xml and modify the contents to create a tenant named Andrew. But tn-andrew does not exist! So we’d want to modify the XML file to change the DN from “uni/tn-COAST” to “uni/tn-andrew”, and the name from “COAST” to “andrew”.
We’ll save as the Configuration Only, Subtree, and XML.
Changing the DN and name attributes of a tenant object.
Once we’re ready to POST it back, we need to remove the tn-COAST object, and either leave it as “uni” (the parent DN) or add the “tn-andrew” to explicitly tell it which object we want to operate on. I recommend including the object name to match to keep the practice consistent with operating other objects where it’s explicitly defined.
Visore
You may have tried curing insomnia by reading the APIC Management Information Model Reference instead of counting sheep. I recommend melatonin supplements instead, and save the MIM Reference for when you have some coffee to help you get through it. In the meantime, the APIC also has an online/searchable utility to display objects, too.
Just click on the sprocket menu in the upper-right corner where you found the API Inspector (see above), and select Object Store Browser instead. A new tab/window will display the Visore object store browser.
Finally, in the same sprocket menu of “Helpful Things” in the upper-right corner, there is an option to “Show Debug Info.”
Enabling this will use the status bar of your browser (usually the bottom edge of the window) to display the object name when you hover your mouse over it.
We’ll include more info on using Visore and the Show Debug Mode in a future post.
That’s all for today’s blog! But more to come on ACI right here on the ACI Board on Cisco Community.
In the meantime, please drop a comment and let us know if this walk through of the APIC API was helpful. Feel free to even comment below on ACI topics you’d like to see discussed here in the near future!
