Knowledge Base

The VMware Knowledge Base provides support solutions, error messages and troubleshooting guides
 
Search the VMware Knowledge Base (KB)   View by Article ID
 

Accessing and using the vCloud Networking and Security 5.1.x REST API (2034410)

Purpose

Representational State Transfer (REST) is an architectural style characteristic of programs that rely on the inherent properties of hypermedia to create and modify the state of an object that is accessible at a URL.

vCloud Networking and Security 5.1.x uses the REST API to perform tasks. You have several choices for programming the vCloud Networking and Security REST API. You can access the vCloud Networking and Security REST API, by using Chrome, Firefox, or cURL. This article explains how you can access the REST API in vCloud Networking and Security using these options and a brief explanation of what can be done.

Resolution

Overview of vCloud Networking and Security REST API
 
vCloud Networking and Security REST API allows you to perform scripted tasks in your vCloud Networking and Security environment. This can be very useful in automating your environment. In addition configurations, and managing users all can be performed from the REST API. In vCloud Networking and Security REST API once a URL of an object is known to a client, the client can use an HTTP GET request to discover the properties of the object. These properties are typically communicated in a structured document with an HTTP content type of XML or JSON, that provides a representation of the state of the object.

To use the vCloud Networking and Security REST API there are certain requirements that must be meet. Review the following in detail to access your environment.
 
Network Port Requirements for vCloud Networking and Security REST API
 
The vShield Manager requires port 443/TCP for REST API requests. Ensure this port is opened on your firewall, and between components of your ESXi hosts, vCenter Server, and vCloud Networking and Security For more information on network ports required for vShield, see Network port requirements for vCloud Networking and Security 5.1.x (2034339).
 
Accessing the vCloud Networking and Security REST API
 
You have several choices to access vCloud Networking and Security REST API. The steps below describe how to access the REST API, using a specific program.
Note: To make XML responses more legible, you can copy and paste them into xmlcopyeditor or pspad.
 
To use the REST API in Chrome:
  1. Download Simple REST Client from the Chrome Web Store, and add it to Chrome.
  2. Click the globe icon to start it in a tab.
  3. The Simple REST Client does not provide certificate checking interface, so use another Chrome tab to Accept or Ignore the lack of SSL certificate.
  4. Type the URL of a REST API you want to access (examples below), and select a method such as GET, POST, or PUT.
  5. In the Headers field, type the basic authorization line: Authorization: Basic YWRtaW46ZGVmYXVsdA== . Click Send. Status, Headers, and Data appear in the Response window.
To use the REST API in Firefox:
  1. Download the RESTClient Mozilla add‐on from the Mozilla Add-on Website, and install it to Firefox.
  2. Click Tools > REST Client to start the add‐on.
  3. Click Login and enter the vShield login credentials, which then appear encoded in the Request Header.
  4. Select a method such as GET, POST, or PUT, and type the URL of a REST API (examples below). You might be asked to Accept or Ignore the lack of SSL certificate. Click Send.
  5. Response Header, Response Body, and Rendered HTML appear in the bottom window.
To use the REST API in cURL :
  1. Download and install cURL from the official cURL web site if not already installed.
  2. In front of the REST URL, the ‐k option avoids certificate checking, and the ‐u option specifies credentials.

    curl -k -u admin:default
    https://<vsm-ip>/api/2.0/services/usermgmt/user/admin

    Note: admin:default are the default username and password in vShield. You may have already changed this if you have performed a security hardening of your environment.
Example URLs in vCloud Networking and Security REST API
 
The following are some URLS you can access in vCloud Networking and Security REST API that maybe useful in your environment. Several more examples are available in the vShield API Programming Guide as well as a more in depth overview of REST API for vShield.
 
Synchronize vShield Manager with vCenter server and identify DNS services

Request:

POST https://<vsm-ip>/api/2.0/global/config

Request Body:

<vsmGlobalConfig xmlns="vmware.vshield.edge.2.0">
<vcInfo>
<ipAddress>10.112.196.22</ipAddress>
<userName>administrator</userName>
<password>123</password>
</vcInfo>
<dnsInfo>
<primaryDns>10.112.192.1</primaryDns>
<secondaryDns>10.112.192.2</secondaryDns>
</dnsInfo>
</vsmGlobalConfig>
 
Configure time and zone
 
Request:
 
POST https://<vsm-ip>/api/2.0/global/config
 
Request Body:
 
<vsmGlobalConfig xmlns="vmware.vshield.edge.2.0">
<timeInfo>
<clock>2011-09-09 09:00:00</clock>
<zone>Pacific</zone>
</timeInfo>
</vsmGlobalConfig>
 
 
Update a Local User Account
 
You can update a local user account including password. If a password is not provided, the existing password is retained. The <userId> variable in the request header should be same as the one specified in XML. The API returns updated information for the user.
 
Request Header:
 
PUT https://<vsm-ip>/api/2.0/services/usermgmt/user/local/<userId >
 
Request Body:
 
<userInfo>
<userId>somebody</userId>
<password>123</password>
<fullname>Person Somebody</fullname>
<email>ps@y.com</email>
<accessControlEntry>
<role>security_admin</role>
<resource>
<resourceId>datacenter-312</resourceId>
...
</resource>
</accessControlEntry>
</userInfo>

See Also

Request a Product Feature

To request a new product feature or to provide feedback on a VMware product, please visit the Request a Product Feature page.

Feedback

  • 4 Ratings

Did this article help you?
This article resolved my issue.
This article did not resolve my issue.
This article helped but additional information was required to resolve my issue.
What can we do to improve this information? (4000 or fewer characters)
  • 4 Ratings
Actions
KB: