Cisco UCS Director REST APIs: Step By Step Tutorial

As I introduced in last article, there are two sets of APIs in UCS Director: north bound APIs, and south bound APIs. The north bound APIs are REST styled, allowing other applications to invoke UCS Director functionalities, or simply retrieve information from UCS Director. We’ll go through the REST APIs in details so that you can quickly get started with it.


Bothered by SLOW Web UI to manage vSphere? Want to manage ALL your VMware vCenters, AWS, Azure, Openstack, container behind a SINGLE pane of glass? Want to search, analyze, report, visualize VMs, hosts, networks, datastores, events as easily as Google the Web? Find out more about vSearch 3.0: the search engine for all your private and public clouds.

To get started, you want to install a UCSD which is packaged as a virtual appliance. We’ll look at version 4.1 of UCS Director. I am not going to detail the deployment process of the UCS Director server, but assume the server is already properly set up. If you have any trouble, just check out the Install Guide from Cisco.

If you don’t have an existing tool to try out REST APIs, you want to install one like the RESTClient which is an add-on to the Firebox browser. Just click on the Tools – Add-ons, you can search for RestClient. I use version 2.0.3. After installing the add-on and restarting Firefox, you should be able to find RestClient under the Tools menu, which leads to the following “page”:

Get API Key

Now, let’s login with UCS Director you have just installed. The default user name and password is admin and admin, pretty straight forward. You should change it in your production environment; otherwise, just keep it as it is. With many servers to manage, I find the “RAM” in my brain is not big enough. So I de-duplicate information by keep them the same. After all, our brain is designed for something better remembering passwords.

On the right side of the page after login, you can find “admin” located on the top right side. Upon clicking on it, you’ll find a popup dialog box titled “User Information”. In the “Advanced” tab, the API key is listed. Don’t try to write it down. Rather, click on the “Copy Key Value” button. Note the “Regenerate Key” button, which could be very help if you want to invalidate the old key and come up with a new one.

Once you have the key copied, go back to the Firefox RESTClient and click on Headers on the top. Just add a new header with name “X-Cloupia-Request-Key” and paste the value of the REST API key. You should see a Headers section above the body section with the newly added HTTP header.

Try Your First REST API Call

Although you can all sorts of methods with REST APIs, the simplest one is simply to use GET method which is normally used to retrieve information. Let’s try one such GET method with cloud resource as follows:


Upon sending the request, you should see response in the Response section right below the Body section. There are several tabs there, but go directly to the last one “Response Body (Preview)” which has pretty print of the response XML and highlights the tags. I found it’s just easier to read than other tabs. I am not going to capture the screen, but copy the response XML instead so that you can see clearly what is there in the body of HTTP response. My blog plugin also has a nice XML syntax highlighter.

      <physicalDatacenter>Default Pod</physicalDatacenter>

There could be multiple cloud elements in the XML response, but I just listed one to save space because they all look very similar in structure.

Yet Another Type of URL and Pattern

What you’ve tried is the simple version of REST APIs that UCS Director supports. There is another type of REST APIs that allows a lot more actions. You can use either POST or GET method on the URL as follows:

POST http://<ucsd-server>/app/api/rest?formatType=json&opName=operationName&opData=operationData

Besides the UCSD server IP address or host name, you can change the values of following in the URL:

  • formatType: could be either xml or json
  • opName: operation name which decides what to do
  • opData: the arguments required by the operation in json format. Even if there is no value needed, you should still need to supply {}. Without the empty place holder, you won’t get valid response back. In fact, in my testing, it just hangs there like forever.

Let’s take a look at a concrete sample URL:


The body of the HTTP response is as follows:

           "userId": "admin",
           "firstName": null,
           "lastName": null,
           "email": null,
           "groupName": null,
           "groupId": 0,
           "role": "Admin"
       "serviceError": null,
       "serviceName": "InfraMgr",
       "opName": "userAPIGetMyLoginProfile"

The URL pattern is indeed very simple. But, you still have to know what operations and their parameters are needed for certain tasks you want to achieve. Besides the UCS Director REST Developer Guide (), there is a powerful built-in tool for the API developers. That is all the next section is about.

Developer Menu

I think this is a shining gem in the UCS Director. By default, this feature is turned off. To turn it on, just go to the “User Information” dialog box we showed you early, and check the “Enable Developer Menu (for this session)”.

Once the developer menu is enabled, you can go check the other GUI pages by clicking on the menus. Let’s take a simple menu path as an example here: Policies – Workflows. On the tool bar right below the “Workflows” tab, you should see “Report Metadata” as the last icon button.

Click on the “Report Metadata,” you should see a dialog box popping up with title “Information” as shown below. Scroll all the way down, you will find a section called “REST API URL.” That is the URL you would need to copy and paste to the RESTClient for the same information as displayed on UCS Director GUI.

With the help of the developer menu, (almost) whatever you can do from the UCS Director, you can easily find out the corresponding URL with opName and opData. Isn’t that wonderful?
This is of course not really equal to programming the REST APIs, but definitely a great tool to get started and familiarized with the UCS Director REST API.

REST API Browser

This is another gem in UCS Director helping developers with the REST APIs. If you have the “Enable Developer Menu” turned on already, you should be able to see it with the “Policies – Orchestration” menu item. In parallel with the first “Workflows” tab, you would see “REST API Browser.”

On the left side of the pane are the folders for tasks. You can navigate the structure and double click any one of the tasks for a dialog box with three tabs on the top: API Examples, Details, Sample Java Code.

With the API Example tab, you can find the URL, HTTP method. You can also select context for the API call and generate a sample XML request, which can be executed by the “Execute REST API” button below. Upon execution, you would see the XML response at the bottom.
The Details tab list API details for the selected task. But the last tab “Sample Java Code” provides you the generate Java code for running the task. That is definitely very helpful to get started with Java programming on the UCS Director REST APIs. I’ll cover that in a later article.

What’s Next?

Now, we are done with the basics of REST APIs of the UCS Director, including the tools like REST API Browser, Developer menu, etc. These are probably good enough for scripting, but not so much for a real integration project which requires programming languages like Java. That is something I will get to soon. Stay tuned.

This entry was posted in Cloud Computing, Software Development and tagged , , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.


  1. Nilesh
    Posted April 4, 2014 at 5:26 am | Permalink

    Hi Steve,

    Thank for this good document. Can you please help me with my post query on UCS director.

    am trying to use below queries


    The above query works fine which returns me service request id say 32, But when i looked into service request panel i do not see this request present and hence i could not see machines details.

    I would like to know what is missing here, Also param2 was mentioned as 1000 does this number has any significant, where should i find the correct parentSRID.

    Thank you for quick response.


  2. Posted April 4, 2014 at 4:34 pm | Permalink

    Hi Nilesh,

    Were you using the same username for submitting the request and looking at the SR panel?


  3. ahmar
    Posted May 31, 2014 at 1:41 am | Permalink

    do you guys know how we can set root login password in UCSD?

  4. Posted May 31, 2014 at 1:37 pm | Permalink

    Yes. You first login as shelladmin, and then you’ll see a menu with numbers before each menu item. Enter the number of “Login as root” (I think it’s 23), the system will prompt you for password for root. After that you can re-login as root user. As always, be careful with root user.


  5. ZeKoU
    Posted November 6, 2014 at 10:30 am | Permalink

    Hi Steve,

    I found this article while trying to solve my problem. Pretty much same as Nilesh in the comment above. I have created one Custom Task with one input parameter. After that I created custom workflow and mapped workflow input parameter to the task input parameter. Now I decided to submit workflow service request through REST API, and this is my call:

    GET{param0:”Get User VMs”,param1:{“list”:[{“name”:”input_0_userId80″,”value”:”amer.test”}]},param2:”1000″}

    I get this response:

    { “serviceResult”:7, “serviceError”:null, “serviceName”:”InfraMgr”, “opName”:”userAPISubmitWorkflowServiceRequest” }

    So my service request got ID. However I don’t see SR on the Organizations->Service Requests section in UCSD.

    I even managed to get logs for the ececution of this workflow through this API call:{param0:”7″,param1:”0″,param2:”null”}

    The output is here:

    I did call both APIs with admin user which I use to see service requests under Organization ->Service Requests section.

  6. Posted November 6, 2014 at 6:02 pm | Permalink

    It’s been a while since I touched it. If I remember correctly, it’s possible for the SR not visible to some users other than the creator due to permission or isolation. To be sure, you can dig out the database to see if the SR exists. Good luck!


  7. Posted September 15, 2015 at 11:27 am | Permalink

    Thanks for sharing your thoughts on cisco. Regards

One Trackback

  • […] Cisco UCS Director REST APIs: Step By Step Tutorial – Formerly known as Cloupia, the new-ish Cisco UCS Director product grants the ability to treat a stack of infrastructure in a more automated and workflow-based manner. Steve Jin has published a few great posts that walk through using UCS-D, including this API discussion that I found both useful and intriguing. […]

Post a Comment

Your email is never published nor shared. Required fields are marked *


You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>


    My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.