Virtual Infrastructure JSON API
About the Virtual Infrastructure JSON API
Starting with vCenter 8.0 Update 1, VMware adds support for a new HTTP/JSON-based wire protocol as an alternative to SOAP/XML. The new protocol is described using the industry-standard OpenAPI specification, version 3.0, and can be used to access the popular VIM APIs. For more information see the OpenAPI Specification and the Web Services Programming Guide, part of the vSphere Management SDK.
Getting Started with the Virtual Infrastructure JSON API
Retrieving the Service Instance with the JSON Protocol
ServiceInstance is a singleton managed object that acts as a gateway to the resources available on the server. You can locate other important singletons such as SessionManager and AuthorizationManager from the properties of the ServiceInstance. ServiceInstance is accessible without authentication, so you can retrieve a reference to the SessionManager which you can use to authenticate a session.
GET Service Instance Get Content
The response is a JSON object that has a sessionManager key which contains a ManagedObjectReference to the SessionManager managed object. The value of the value key of this ManagedObjectReference must be used for the moId path parameter when invoking SessionManager operations.
For example, the SessionManager moId can be obtained by issuing a GET with curl like this:
SESSION_MANAGER_MOID=$(curl -s https://$VC/sdk/vim25/8.0.3.0/ServiceInstance/ServiceInstance/content \
| jq .sessionManager.value \
| xargs -t)
Authenticating a JSON Client with the Session Manager
Most method calls must carry a session ID to authenticate with the server at the time of the call. The session ID is a temporary substitute for username and password, thereby limiting risk to the principal's credentials.
For example, the Login operation can be performed by issuing a POST with curl and capturing the vmware-api-session-id HTTP header from the result:
curl -v "https://$VC/sdk/vim25/8.0.3.0/SessionManager/$SESSION_MANAGER_MOID/Login" \
-H 'Content-Type: application/json' \
-d '{"userName": "Administrator@vsphere.local", "password": "betyoucantguess"}'
< HTTP/1.1 200 OK
< content-type: application/json
< vmware-api-session-id: c3ab4eb20bf5639b47af96e06118428579c40266
...
Use the session ID in subsequent calls
On subsequent API calls you will need to include the session ID returned in the above call. Copy the session ID header into your request, as follows:
GET /sdk/vim25/8.0.3.0/VirtualMachine/vm-495/config
vmware-api-session-id: c3ab4eb20bf5639b47af96e06118428579c40266
Transcoder API
Developers migrating to VI/JSON from SOAP/XML based automations may find useful the Transcoder API providing XML to JSON Data Object conversion.