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.2.0/transcoder HTTP/1.1
Host: {vcenter-address}
Accept: application/json
Content-type: application/xml
vmware-api-session-id: {session-id}
Content-Length: 396
<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">
<name>sample-vm</name>
<guestId>guest</guestId>
<annotation>Sample</annotation>
<files>
<vmPathName>[datastore1]</vmPathName>
</files>
<numCPUs>1</numCPUs>
<memoryMB>4</memoryMB>
</obj>
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
}