Getting Started with Cisco UCS Manager XML API Guide

Cisco Unified Computing System (UCS) Manager provides a robust XML API that allows administrators and developers to automate, monitor, and manage UCS infrastructure programmatically. If you’re looking to get started with the Cisco UCS Manager REST API using XML, this guide will walk you through the fundamentals, authentication, request structure, and practical tips for your first interactions.

What is the Cisco UCS Manager XML API?

The Cisco UCS Manager XML API is a programmatic interface that accepts XML documents over HTTP or HTTPS, enabling full access to the UCS management information tree. This tree represents all managed objects (MOs) such as chassis, blades, adapters, and policies, and can be queried or configured via the API. The API is transactional and supports both single-object and hierarchical operations, ensuring changes are either fully applied or rolled back on error.

Key Concepts

Management Information Tree: All UCS configuration and state data is organized hierarchically and accessible via the API.
Classes, Methods, Types: The API uses classes to represent objects, methods to perform actions, and types to define object properties.
Forgiving Mode: The API ignores missing or incorrect attributes, applying defaults or rolling back changes if needed.
Session-Based Authentication: Interactions require a session cookie obtained via login.

Authenticating with the XML API

Before making any API calls, you must authenticate and obtain a session cookie. This is done via the aaaLogin method, which requires a username and password. Here’s how you can do it using cURL:

Bash

curl -d "<aaaLogin inName='admin' inPassword='password'></aaaLogin>" http://<UCSM_IP>/nuova

The response will contain an outCookie attribute, which you must include in subsequent requests to maintain your session.

Example XML for Login:

XML

<aaaLogin inName="admin" inPassword="password" />

Extracting the Cookie in vRO:

Code snippet showing the REST API login request for Cisco UCS Manager using XML, including session cookie extraction.

Making Your First API Call

Once authenticated, you can perform various operations. For example, to query information about a specific blade server:

Request:

XML

<configResolveDn dn="sys/chassis-1/blade-1" cookie="<real_cookie>" inHierarchical="false"/>

Sample cURL Command:

Bash

curl -d "<configResolveDn dn='sys/chassis-1/blade-1' cookie='<real_cookie>' inHierarchical='false'/>" http://<UCSM_IP>/nuova

Response:
The API will return an XML response with the requested information or a confirmation of the action taken.

Common Methods

configConfMo: Configure a single managed object.
configConfMos: Configure multiple objects.
configResolveDn: Query a specific object by its distinguished name.
eventSubscribe: Subscribe to event notifications for state changes.
configConfRename: Rename a single managed object.

Example:

JavaScript

var request = RestHost.createRequest("POST", "/", '<configConfRename cookie="'+cookie+'" dn="org-root/ls-'+serviceProfileName+'" inHierarchical="true" inNewName='+newName+'/>');

Best Practices and Tips

Use HTTPS: Always use HTTPS in production for secure communication.
Session Management: Refresh your session using aaaRefresh before the cookie expires (default: 600 seconds).
Error Handling: Check the response attribute in XML responses for “yes” (success) or “no” (failure).
No XML Declaration: Do not include XML version or DOCTYPE lines in your API documents.

Example: Logging In to UCS using vRO JavaScript

JavaScript

///This is just an example code. Adapt this code to your environment and use-case.

// This script is used to manage UCSM login sessions and handle cookie expiration.
// It checks if the current session cookie is valid and if not, it logs in again to obtain a new cookie.

// Get creds from Configuration Element (Optional)
var ucsm_user = configFile.getAttributeWithKey('ucsm_usr').value;
var ucsm_pass = configFile.getAttributeWithKey('ucsm_pass').value;
var currentCookie = configFile.getAttributeWithKey('cookie').value;

// Create a new session request using the current cookie if it exists
var newSession = (RestHost.createRequest("POST", "/", '<configResolveDn dn=sys cookie="' + currentCookie + '"/>')).execute();

// Check if the session is invalid based on the content length of the response
if (newSession.contentLength < 250) { // Content length < 250 means the request is unsuccessful and the cookie is expired
    // Log that the cookie has expired and a new login will be initiated

    // Create a login request with the username and password
    var login = RestHost.createRequest("POST", "/", "<aaaLogin inName='" + ucsm_user + "' inPassword='" + ucsm_pass + "'></aaaLogin>");
    var response = login.execute();

    // Extract the response content as a string
    var str = response.contentAsString;

    // Use XML parsing to extract the new cookie value from the response
    var xml = new XML(str);
    var cookie = xml.@outCookie.toString();

    // Log the new cookie value
    System.debug('Cookie is: '+ cookie);

    // Update the configuration file with the new cookie value
    configFile.setAttributeWithKey('cookie', cookie);
} else {
    // Return the current cookie if it is still valid
    System.debug('Cookie is still valid.');
    cookie = currentCookie;
};

// Return the valid cookie value
return cookie;

You can also convert XML to JSON if needed using vRO library action.

JavaScript

var json = System.getModule("com.vmware.library.http-rest").xml2json(xmlResponse);

Resources

Cisco UCS Manager XML API Programmer’s Guide: Comprehensive official documentation with detailed examples and reference.
Developer Communities & SDKs: Cisco provides PowerShell modules and Python SDKs to make working with the XML API easier1.

Conclusion

The Cisco UCS Manager XML API is a powerful tool for automating and managing your UCS infrastructure. By understanding its hierarchical model, authentication process, and XML-based request/response structure, you can quickly start building scripts and integrations to streamline your data center operations. For deeper dives and advanced use cases, consult the official documentation and explore available SDKs for your preferred programming language.