vSphere REST API and C++ (Part 1)

One of the new features in vSphere 6.5 is the vSphere REST API. I’ve used the Web Services SDK before and it has never appeared as elegant as other automation APIs I’ve worked with, so the introduction of this held a lot of promise.

I rarely see examples for REST services in C++ and as it’s my chosen language and I’ve occasionally used “cpprestsdk” (previously known as Casablanca) I wondered if I could put something together. This is the first article in a series playing around with what is possible.

We can browse the API by connecting to our local vCenter via the URL https://<Your vCenter FQDN>/apiexplorer/ and see what we can do. An overview of the process of a session is:

  1. Send a POST request to /rest/com/vmware/cis/session and respond to the basic authentication request.
  2. The response contains an authentication token which represents the session id.
  3. For future requests pass the token in the headers as the value “vmware-api-session-id”.

The SDK and the reference guide for the REST API are available at https://developercenter.vmware.com/web/sdk/65/vsphere-automation-rest.

The Code

The aim of this article is to show the authentication process and make a sample request.

This makes the authentication request:

web::http::client::http_client_config config;
credentials cred(U("administrator@vsphere.local"), "password");

http_client client(vcenter_url.c_str(), config);
uri_builder builder(U("/rest/com/vmware/cis/session"));

std::wstring token = L"";
create_task(client.request(methods::POST, builder.to_string())).then([](http_response response) {
  printf("SSO Request Response Status Code: %d\n", response.status_code());
  return response.extract_json();

}).then([&token](web::json::value v) {

  if (v.has_field(U("value"))) {
    json::value f = v.at(U("value"));
    token = f.as_string();
    wprintf(L"SSO Token value: %s.\n", f.as_string().c_str());

}).then([](task t) {
  try {

  catch (const std::exception& e) {
    printf("Exception: %s\n", e.what());


if (token.length() > 0) {
  printf("Successfully authenticated against SSO.\n");

Most of the code above are is about how we use the cpprestsdk. The basic authentication response is handled by creating a credentials object and assigning it the configuration for our http_client. We also disable SSL certificate verification as we are using self signed certificates. If you are writing something for a secure environment then it’s probably a good idea not to do this 😉

The request is made at line 10 and the task returns the result in a json format (line 12). We then look for an entry with the name “value” and make a note of what it is set to – this is our token. The last part of the concurrency task chain is for handling any exceptions.

The code below will is an example request to vCenter that will use the newly retrieved session token.

web::http::client::http_client_config vc_config;
http_client vc_client(vcenter_url.c_str(), vc_config);

uri_builder vc_vm_uri(U("/rest/vcenter/host"));

http_request vc_req(methods::GET);
vc_req.headers().add(U("vmware-api-session-id"), token.c_str());

create_task(vc_client.request(vc_req)).then([](http_response response) {
  printf("/rest/vcenter/host Request Status Code: %d\n", response.status_code());
  return response.extract_string();

}).then([](utility::string_t text) {
  printf("The response was:\n");


The code above will create a request and pass the token as the “vmware-api-session-id” value. As can be seen, we are still disabling SSL certificate verification but we are not passing credentials – the session id is enough.

The request will be sent to “/rest/vcenter/host” (line 5), which retrieves information about the hosts added to the vCenter. Once the request is made, the output is printed out to the screen in the JSON format.

We could add a final task segment to catch any exceptions that occur in the chain – there is no particular reason for why it is missing.

An Example

Below is a screenshot of the output of the program – I’ve blanked out the address and password of my home lab, though you can see that after a successful authentication information about two hosts is returned.

Full Source

The source is available on GitHub – https://github.com/nelons/vSphereRestApi/tree/master/part1. It was written in Visual Studio 2015 Community Edition and uses the cpprestsdk nuget package (and has UNICODE enabled).

It is not optimised or efficient code, but is meant to be straight forward to read and understand for near beginners (as some understanding of concurrency task code is required).

Comments, suggestions or errors – please let me know !