Virtual Infrastructure Wire Format Transcoder APIs

Transcoder API

Overview

Introduced in vCenter 8.0 U2, the Transcoder API allows users to convert data objects from their XML representation to JSON and vice versa.

Through the Virtual Infrastructure JSON API users are enabled to access vCenter APIs via a JSON-based wire protocol, an alternative to the SOAP/XML. The incentive behind the creation of the Transcoder API is to aid developers migrating their vCenter automations from SOAP/XML to VI/JSON.

Additionally, the Transcoder API enables developers to intertwine different SDKs (SOAP and JSON based) in a single automation by transcoding data objects from one runtime to another.

Usage

The Transcoder API is comprised of a single endpoint - /sdk/{namespace}/{release}/transcoder, moreover, a single operation, and is part of the VI/JSON APIs - available under the common path /sdk/{namespace}/{release}. Additional to the path parameters namespace and release, operation specific parameters are:

A valid VI data object to be transcoded, serialized in XML or JSON format, present in the HTTP body.
The format the data object is transcoder from, denoted by the Content-type header.
The format the data object is transcoded to, denoted by the Accept header.
An optional query parameter target_release used to downgrade the data object to a previous release according to the rules for backward compatibility.

transcode is available only through valid authentication. Authenticated access is granted through the vmware-api-session-id header. For more details on vmware-api-session-id see the VI/JSON landing page.

Exclusively for the transcoder service, a valid vmware_soap_session cookie header also provides authenticated access. This particular authentication variant allows existing SOAP clients to consume the transcoder easily.

The vmware_soap_session cookie header:

cookie: vmware_soap_session="{soap-session-id}"

is obtainable through the SOAP based vim.SessionManager#Login.

As an example, an HTTP request for transcoding a minimalistic, XML-serialized vim.vm.ConfigSpec looks like:

POST /sdk/vim25/8.0.3.0/transcoder HTTP/1.1
Host: {vcenter-address}
Accept: application/json
Content-type: application/xml
vmware-api-session-id: {session-id}
Content-Length: 396

&lt;obj versionId="2.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns="urn:vim25" xsi:type="VirtualMachineConfigSpec"&gt;
   &lt;name&gt;sample-vm&lt;/name&gt;
   &lt;guestId&gt;guest&lt;/guestId&gt;
   &lt;annotation&gt;Sample&lt;/annotation&gt;
   &lt;files&gt;
      &lt;vmPathName&gt;[datastore1]&lt;/vmPathName&gt;
   &lt;/files&gt;
   &lt;numCPUs&gt;1&lt;/numCPUs&gt;
   &lt;memoryMB&gt;4&lt;/memoryMB&gt;
&lt;/obj&gt;

The conversion is from Content-type: application/xml to Accept: application/json, hence, the response is a JSON serialized VirtualMachineConfigSpec:

{
    "_typeName": "VirtualMachineConfigSpec",
    "name": "sample-vm",
    "guestId": "guest",
    "annotation": "Sample",
    "files": {
        "_typeName": "VirtualMachineFileInfo",
        "vmPathName": "[datastore1]"
    },
    "numCPUs": 1,
    "memoryMB": 4
}

Operations

POST

Transcoder Transcode

Transcodes a data object from XML to VI/JSON or vice versa.