Building JSON Request URLs

The service endpoint for the JSON API is determined by the vCenter Server address and the API version that the client prefers for the response. These data form part of the service URL.

All requests in the JSON API specify a managed object. Some requests retrieve properties of a managed object. Other requests invoke a method on a managed object.

The parts of the service URL are as follows:

1. scheme = 'https://'
2. domain = vCenter Server IP address or FQDN
3. The URL path contains the following parts:
   1. endpoint = '/sdk/vim25'
   2. version = '8.0.1.0'
   3. A managed object reference, generated by the server, which has two subparts, type and value, where:
      1. type is the name of a type of managed object, such as Folder or VirtualMachine or ServiceInstance
      2. value is a unique identifier (within this vCenter Server instance) for a specific object of the type named, such as group-d1 or vm-015 or ServiceInstance.
         The object notation must be serialized as two strings separated by a slash ( /). For example: 'Folder/group-d1'.

         def serialize_moref_for_request_url(moref):
           return('{}/{}'.format(moref['type'], moref['value']))

   4. A property name or method name, such as childType or CreateVM

An example request URL to retrieve the type or types of managed objects that a folder can contain::

>>> scheme = 'https://'
>>> domain = 'vcenter.example.com'
>>> endpoint = '/sdk/vim25'
>>> version = '8.0.1.0'
>>> motype = 'Folder'
>>> moid = 'group-d1'
>>> moref = motype + '/' + moid
>>> property = 'childType'
>>> url = scheme + domain + endpoint + '/' + version + '/' + moref + '/' + property
>>> print(url)
https://vcenter.example.com/sdk/vim25/8.0.1.0/Folder/group-d1/childType

An example request URL to cancel a long-running operation:

...
>>> motype = 'Task'
>>> moid = 'task-124'
>>> moref = motype + '/' + moid
>>> method = 'Cancel'
>>> url = scheme + domain + endpoint + '/' + version + '/' + moref + '/' + method
>>> print(url)
https://vcenter.example.com/sdk/vim25/8.0.1.0/Task/task-124/Cancel