Introducing VI/JSON – a modern wire protocol for vSphere management

One of the strengths of the VMware vSphere is its vast API offering. With over a thousand APIs ranging from essential VM operations to storage and network virtualization to clustering and resource management, organizations of all sizes can customize vSphere to their specific needs and automate various workflows to save time and expenses.

Since their inception over 15 years ago, Virtual Infrastructure (VI) management APIs have gained wide adoption. Numerous products and countless scripts are designed around these APIs, and many developers are familiar with their development model. At the same time, VI APIs are based on the industry-standard SOAP protocol, which in turn is designed around XML. Although powerful, XML proved over the years to be a complex data format with its share of security issues. In light of these challenges, developers and system designers turn to JSON as a replacement for XML in the API domain.

To address demand and ease the integration into JSON-only environments ranging from Web browsers to modern programming languages like Go, VMware introduces a new JSON-based, REST-like protocol named VI/JSON. The new protocol is a modern alternative to the aging SOAP and exposes the same VI APIs on the same endpoint with the same security model. An explicit goal of the new VI/JSON protocol is to make the transition from SOAP as easy as possible for most VI APIs consumers. Furthermore, for SDK-based applications, the migration to VI/JSON can be done entirely in the platform with minimal application-side changes.

In addition to preserving full API backward compatibility, the new protocol provides direct access to so-called managed properties – nearly 300 types of records representing the state of various virtualized items managed by vSphere, ranging from VMs to networks, hosts, clusters, etc. Previously, managed properties were only indirectly accessible through the Swiss army knife tool Property Collector. Today, a simple HTTP GET request can access every managed property.

For VI/JSON, REST-like means that managed resources and operations are encoded in the request URL instead of within the message body, as required in SOAP. This change provides numerous benefits: easier integration within API-level firewalls, straightforward traffic analysis, and simpler scripting. Similarly, the JSON-based data encoding will ease the development efforts for many VI APIs consumers.

Last but not least, the security aspects are also improved. Instead of relying on HTTP cookies for session identification, the new protocol uses a dedicated HTTP header, preventing the classical attack known as Cross-Site Request Forgery, where a third party might steal the user identity.

To offer a taste of the new protocol, the following request can be used to power on a VM (the HTTP protocol headers are skipped for brevity):

The equivalent SOAP request looks like the following. Note the mandatory body, which is not required for simple VI/JSON requests.

The new protocol is provided by default with the vSphere 8.0U1 release. The official documentation is available at https://developer.vmware.com/apis/vi-json/latest/

This blog post is the first in a series with examples that examine the protocol in depth.

Follow us on Twitter @VMware_API_team and send us any feedback.