vmware-archive / vsphere-automation-sdk-rest

REST (Postman and JavaScript) samples and API reference documentation for vSphere using the VMware REST API

Discontinued!

The vsphere-automation-sdk-rest has been discontinued. This repo is a READ ONLY repo. Refer below links for REST API documentation and Postman samples.

REST API Documentation

vSphere Automation REST API Postman Resources and Samples

VMware vSphere Automation SDK for REST

Table of Contents

• Abstract
• Intended Audience
• What’s in the SDK?
• Submitting samples
  • Required Information
  • Suggested Information
  • Contribution Process
  • Code Style
• Resource Maintenance
  • Maintenance Ownership
  • Filing Issues
  • Resolving Issues
  • VMware Sample Exchange
• Repository Administrator Resources
  • Board Members
  • Approval of Additions
• VMware Resources

Abstract

The VMware vSphere Automation SDK for REST enables programmatic access to vSphere. The SDK includes Postman examples.

Supported vCenter Releases:

All samples support vCenter 6.7. Tagging samples also support vCenter 6.0.

Intended Audience

The VMware vSphere Automation SDK for REST is intended for the following audiences:

• Developers looking for REST samples for the REST APIs

What’s in the SDK?

The VMware vSphere Automation SDK for REST provides a client SDK that contains samples that demonstrate how to use the vSphere Automation REST API and sample code. The following table contains a brief description of the contents of the vSphere Automation SDK for REST.

Directory structure (under VMware-vSphere-Automation-SDK-REST):

Directory	Contents
samples/postman	Postman samples that demonstrate how to construct REST API requests for Virtual Machine Operations.

Submitting samples

Developer Certificate of Origin

Before you start working with this project, please read our Developer Certificate of Origin. All contributions to this repository must be signed as described on that page. Your signature certifies that you wrote the patch or have the right to pass it on as an open-source patch.

Required Information

The following information must be included in the README.md or in the sample docstring in case a README already exists in same folder.

• Author Name
  • This can include full name, email address or other identifiable piece of information that would allow interested parties to contact author with questions.
• Date
  • Date the sample was originally written
• Minimal/High Level Description
  • What does the sample do?
• Any KNOWN limitations or dependencies

Suggested Information

The following information should be included when possible. Inclusion of information provides valuable information to consumers of the resource.

• vSphere version against which the sample was developed/tested
• SDK version against which the sample was developed/tested
• Additional Version information for any dependencies against which the sample was developed/tested

Contribution Process

• Follow the GitHub process
  • Please use one branch per sample or change-set
  • Please use one commit and pull request per sample
  • Please post the sample output along with the pull request
  • If you include a license with your sample, use the project license

Resource Maintenance

Maintenance Ownership

Ownership of any and all submitted samples are maintained by the submitter.

Filing Issues

Any bugs or other issues should be filed within GitHub by way of the repository’s Issue Tracker.

Resolving Issues

Any community member can resolve issues within the repository, however only the board member can approve the update. Once approved, assuming the resolution involves a pull request, only a board member will be able to merge and close the request.

VMware Sample Exchange

It is highly recommended to add any and all submitted samples to the VMware Sample Exchange: https://code.vmware.com/samples

Sample Exchange can be allowed to access your GitHub resources, by way of a linking process, where they can be indexed and searched by the community. There are VMware social media accounts which will advertise resources posted to the site and there's no additional accounts needed, as the VMware Sample Exchange uses MyVMware credentials.

Repository Administrator Resources

Board Members

Board members are volunteers from the SDK community and VMware staff members, board members are not held responsible for any issues which may occur from running of samples from this repository.

Members:

• Ravi Chadalawada (VMware)
• J.R. Garcia (VMware)

Approval of Additions

Items added to the repository, including items from the Board members, require 2 votes from the board members before being added to the repository. The approving members will have ideally downloaded and tested the item. When two “Approved for Merge” comments are added from board members, the pull can then be committed to the repository.

VMware Resources

• vSphere Automation SDK Overview
• Getting Started Blog post
• VMware Code
• VMware Developer Community
• VMware vSphere REST API Reference documentation.
• VMware VMC REST API Reference documentation.
• VMware REST forum

vsphere-automation-sdk-rest's Issues

How change clone vm ip address ?

Hello,

How change clone vm ip address for linux(centos7) and anything Os ?

I have a example with powershell;

"Invoke-VMscript -VM "$clone_name" -ScriptText "echo -e NAME=ens32'\n'TYPE=Ethernet'\n'BOOTPROTO=static'\n'DEFROUTE=yes'\n'PEERDNS=yes'\n'PEERROUTERS=yes'\n'IPV4_FAILURE_FATAL=no'\n'ONBOOT=yes'\n'IPADDR=$VDS_ip'\n'NETMASK=$VDS_netmask'\n'GATEWAY=$VDS_gateway > $filepath" -GuestUser $guest_username -GuestPassword $guest_password -scriptType bash | Out-Null"

Get VM IP

Hello!

I have been scanning the net for information as how to acquire IP information of a created VM, but I am at a loss. Doing a REST request to {vcenter}/rest/vcenter/vm/{id} returns every possible information but the one I am looking for. The Vcenter web application however can acquire this information, so it is stored somewhere. How would I go by getting it?

test

SSO example results in SAXParseException

Attempting to use thesso.js example with valid credentials results in a SAXParseException:

<?xml version="1.0" ?>
<S:Envelope
	xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
	<S:Body>
		<S:Fault
			xmlns:ns4="http://www.w3.org/2003/05/soap-envelope">
			<faultcode>S:Server</faultcode>
			<faultstring>org.xml.sax.SAXParseException</faultstring>
		</S:Fault>
	</S:Body>
</S:Envelope>

Retrieving IPv4 address of deployed VM

Hi guys. My org is currently using vSphere 6.7. I don't foresee any plans of upgrade so far.
When we deploy VM's in our org, the IPv4 address is set as an property under additional parameters in the request body of "https://{{vc}}/rest/com/vmware/vcenter/ovf/library-item/id:{{libraryitemID}}?~action=deploy" API. (please see the snippet below of the request body).

My question is, is there any way i can search vSphere client to retrieve VMs that are deployed on the same IP? is it possible to do a VM search based on, for example, "ip0" property in the below snippet? can i do a search by IP address using APIs? (i know this is possible using SDK, but needed it to work using APIs)

NOTE:

1. https://{{vc}}/rest/vcenter/vm/vm-6768/guest/identity - This API returns only one IP, whereas i would need the entire list of IP addresses.
2. I hear that the API to return ALL IP's was released in vSphere API version 7.0 but (i think) as i don't have that version, i get a 404 error.

SNIPPET:
{
"deployment_spec":
{
"additional_parameters":[
{
"@Class": "com.vmware.vcenter.ovf.property_params",
"properties":[
{
"instance_id": "xxxxx",
"class_id": "vami",
"description": "Network IPV4 address",
"id": "ip0",
"label": "Network IPV4 address",
"category": "xxxxx",
"type": "ip",
"value": "{{IPv4Address}}",
"ui_optional": false
},

vm/{vm}/guest/identity should return all IPs

Regarding #21, it is not acceptable that the answer is like "yeah we're only returning one IP (by design)". All APIs should return the same values IMHO, if implemented.

When there are multiple IPs used by the guest, all should be returned, preferably as a list and not a comma-separated string.

Thanks.

unable to create vm with distributed switches

creating a vm with nics needs provide backing info:
"backing" : { "distributed_port" : "string", "type" : "STANDARD_PORTGROUP", "network" : "obj-103" },

with a default switch works fine:
"backing" : { "type" : "STANDARD_PORTGROUP", "network" : "obj-103" },

but not when you have a distributed switch:
"backing" : { "distributed_port" : "string", "type" : "DISTRIBUTED_PORTGROUP", "network" : "obj-103" },
with rest api i am unable to find out the value (id) for distributed_port.

Include VM Folder in vm api

Summary

Add VM Folder Name when fetching vm details

• What is the change?
  Add VM Folder Name when fetching vm details
• Why should it go into the vSphere Automation SDK?
  It helps simplify fetching this data which otherwise is very complex
• Does this change impact existing behaviors? If so how?
  Not sure
• If this change introduces a new behavior, is this behavior accessible?
  Not sure

Use case

Currently it takes very long to fetch this data using very complicated means.

Workarounds

Currently it takes very long to fetch this data using very complicated means.

Trouble with Instant Clone

Hello,
I have a problem with Instant clone via REST API.
My request looks like this and I sent it to {url}/rest/vcenter/vm?action=instant-clone
{
"spec": {
"bios_uuid": "test4",
"guest_OS": "WINDOWS_7_SERVER_64",
"name": "Klon",
"source": "vm-40316"
}
}

in response i have :(

{
"type": "com.vmware.vapi.std.errors.unexpected_input",
"value": {
"messages": [
{
"args": [
"[action]",
"operation-input"
],
"default_message": "Found unexpected fields [action] in structure 'operation-input'.",
"id": "vapi.data.structure.field.unexpected"
}
]
}
}

What am I doing wrong?

how to access the rest api from python?

Hi,
I try to access our vSphere 6.7 through python requests. I looked at the JavaScript samples and came up with the following code

#!/usr/bin/env python3
# -*- coding: UTF-8 -*-
 
import requests
import json
 
prefix = 'https://vc.internal.corp/rest'
 
ses = requests.Session()
ses.headers['Content-Type'] = 'application/json'
ses.headers['Accept'] = 'application/json'
 
print("Login")
res = ses.post(prefix + "/com/vmware/cis/session",
    auth = ('user', '_passwd_'),
    data = "",
    verify = False
)
res.raise_for_status()
 
 
print("List")
res = ses.get(prefix + '/vcenter/vm',
    verify = False
)
print(json.dumps(res.json(), indent=4, sort_keys=True))
 
 
print("Logout")
res = ses.delete(prefix + "/com/vmware/cis/session",
    verify = False
)
res.raise_for_status()

unfortunately the result is not what I expected

Login
List
{
    "type": "com.vmware.vapi.std.errors.operation_not_found",
    "value": {
        "messages": [
            {
                "args": [
                    "com.vmware.vcenter.VM"
                ],
                "default_message": "Cannot find service 'com.vmware.vcenter.VM'.",
                "id": "vapi.method.input.invalid.interface"
            }
        ]
    }
}
Logout

Any idea what's wrong?
Kind regards
BoomerB

Enable vApp options and configure OVF environment transport for a VM

Is it possible to enable vApp options and also choose which transport to use to pass the OVF environment to the guest with the REST APIs?

My goal is to pass some custom parameters to the VM guest OS so it can configure itself. I was playing around with the idea of putting them in the OVF and then reading them with "vmtoolsd --cmd "info-get guestinfo.ovfenv" on the guest, which we are guaranteed to have. From what I read of the python SDK it is doable but ideally I don't want to introduce that dependency.

Need OVF deploy example including static ip assignment

Greetings, I hope this is the right avenue for a feature request regarding a sample of OVF deploy which should include provisioning network (static ip) as I don't seem to be able to deduce this from the documentation. If I should be looking for support elsewhere, please advise. Thanks in advance :)
ps. here is a link to stackoverflow question : http://stackoverflow.com/questions/43767814/example-deployment-of-ovf-with-rest-api-including-network-ip-provisioning

Missing VM information from .../vcenter/vm/{vm}

I noticed recently while writing a CMDB integration, that {cluster} is not included in the information retrieved from the above endpoint. {resource_pool} is not included as well, which could be a way to work around the issue.

Also, (since we're talking missing information), while the above endpoint shows datastore, it does not show datastore cluster, which would really be handy to have, as the VM can move at any given point in time.

Broken link

Broken link on readme file and https://code.vmware.com/samples/2562/vsphere-automation-rest-api-postman-resources-and-samples

"vSphere-Automation-Rest-Resources.postman_collection.json provides the individual API resources. They are standalone requests that you can execute or use to build up an end to end workflow."

Points to:

https://github.com/vmware/vsphere-automation-sdk-rest/blob/master/samples/postman/vSphere-Automation-Rest-Resources.postman_collection.json

It should point to:

https://github.com/vmware/vsphere-automation-sdk-rest/blob/master/samples/postman/vSphere-Automation-REST-Resources.postman_collection.json

Rest vs REST

How to determine available datastores and networks given a cluster + host?

Via the REST API I need to determine datastores and networks available/accessible to a given cluster + host combination. How is this possible? Hosts is not available as one of the filters for datastores nor networks.

https://vcenter6-eqx.noc.lan/rest/vcenter/host/{host} is not available

GET /rest/vcenter/host/{host} is currently not implemented.
So there seems to be no way to obtain host information (such as CPU type).
However the corresponding command exists in the other SDKs in Perl or PowerCLI
and the information exists in vSphere.

Link to REST-API-resources is wrong

Describe the bug

When you click on the link for the api resources either in the readme of this repo (it's a link to the blob there) or in the official vmware site (where it's a link to the raw file). The link is: vSphere-Automation-Rest-API-Resources.postman.json.

However, instead of getting the json file with the samples you get githubs "page not found" page.

How to reproduce

Click the link either in this issue, the readme or the vmware-page I linked.

Expected behavior

You get the json file (downloading it directly would also be nice instead of just displaying the raw file but that's something else).

Additional notes

As far as I understand, this error got introduced by the latest commit where the file in question was renamed from vSphere-Automation-Rest-API-Resources.postman.json to vSphere-Automation-REST-Resources.postman_collection.json without correcting the link.

You can prove this by replacing master with the commit hash from the commit before 6d860a4 (latest commit) which results in this link and this works of course.

Setting PropertyParams when deploying VM from OVF

I'm attempting to to set PropertyParams when deploying a VM from a OVF library template using the following API POST https://{server}/rest/com/vmware/vcenter/ovf/library-item/id:{ovf_library_item_id}?~action=deploy.

I've yet to get this to work however. When sending the parameters, I end up with the following error to the POST: Could not convert field 'properties' of structure 'com.vmware.vcenter.ovf.property_params'. Changing the param structure (below) results in them simply being ignored.

Below is a segment of the POST body showing an attempt to set a value to my_property_name:

deployment_spec : {
  /* ... */

  additional_parameters : [
    {
      type : 'PropertyParams',
      properties : [
        {
          id : 'my_property_name',
          value : 'foo',
        }
      ]
    }
  ]
}

Given the following segment in the OVF:

<ProductSection>
  <Info>Information about the installed software</Info>
  <Product>MyProduct</Product>
  <Vendor>MyCompany</Vendor>
  <Version>1.0</Version>
  <Category>Config</Category>  
  <Property ovf:userConfigurable="true" ovf:type="string" ovf:key="my_property_name" ovf:value="">
    <Label>My Property</Label>
    <Description>A custom property</Description>
  </Property>
</ProductSection>

What should the additional_parameters structure look like if this is not correct, or is this a bug?

Note that I have posted to Stack Overflow (https://stackoverflow.com/questions/47912744/propertyparams-when-deploying-vm-from-ovf) and the forums (though perhaps the wrong ones) as well (https://communities.vmware.com/thread/578802)

OpenAPI spec for vSphere automation REST?

Is there an swagger/openapi specification for the vsphere automation API? It can be used to generate clients for languages without vmware-provided bindings (e.g. Go).

What will I write in the "source" section when I import the clone?