vCloud Air Platform Programmer's Guide vCloud Air 5.6 This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs.
vCloud Air Platform Programmer's Guide You can find the most up-to-date technical documentation on the VMware Web site at: http://www.vmware.com/support/ The VMware Web site also provides the latest product updates. If you have comments about this documentation, submit your feedback to: docfeedback@vmware.com Copyright © 2015 VMware, Inc. All rights reserved. Copyright and trademark information. VMware, Inc. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com 2 VMware, Inc.
Contents About this Programmer's Guide 5 1 About the vCloud Air Platform APIs 7 The VMware APIs for Cloud Automation 7 XML Namespace Identifiers 8 Overview of Object Types 8 Link Relationships in the Object Types 9 API Versioning 10 Roles for the APIs for Cloud Automation 11 Authentication and Authorization 11 vCloud Air Platform APIs Schema Reference 12 Java Code Samples for Cloud Automation 12 About the Examples in this Programmer's Guide 13 2 Hello vCloud Air : A RESTful Workflow 15 Log in to vCloud
vCloud Air Platform Programmer's Guide 4 VMware, Inc.
About this Programmer's Guide The vCloud Air Platform Programmer's Guide provides information about version 5.6 of the vCloud Air Platform APIs. ® VMware provides many different APIs and SDKs for applications and goals. This guide provides information about the vCloud Air Platform APIs (formerly known as the vCloud Hybrid Service Extensions) for developers who create RESTful clients for use with vCloud Air subscription services; specifically, the Dedicated Cloud and Virtual Private Cloud services.
vCloud Air Platform Programmer's Guide 6 VMware, Inc.
About the vCloud Air Platform APIs 1 The vCloud Air Platform APIs provide support for developers who are building interactive clients of vCloud Air using a RESTful application development style. vCloud Air clients and vCloud Air servers communicate over HTTP, exchanging representations of vCloud Air objects. These representations take the form of XML elements. vCloud Air clients make HTTP requests to the server and retrieve the information the clients need from the server's responses.
vCloud Air Platform Programmer's Guide XML Namespace Identifiers A response typically includes all the XML namespace identifiers that the server uses to validate it, in addition to other attributes that specify the schema locations searched during validation. The following fragment shows the attributes and prefixes of the XML namespace identifier that appear in a typical response for the vCloud Air Platform APIs: PAGE 9Chapter 1 About the vCloud Air Platform APIs Table 1‑1. Object Type Descriptions (Continued) Object Type Description Class Value ComputeType Represents a reference to a Compute service. Contains a list of virtual data centers contained in the Compute service. The Compute service for a Dedicated Cloud contains zero or more virtual data centers. The Compute service for Virtual Private Cloud always contains one virtual data center. vnd.vmware.vchs.
vCloud Air Platform Programmer's Guide Elements References Compute VdcRef VcloudSession VdcLink Each reference contains the URL and media type of the referenced object. The following diagram shows where references provide URLs to other elements (solid black arrow). Additionally, The Compute and VcloudSession elements contain up links to the ServiceList and Compute elements, respectively. Figure 1‑1.
Chapter 1 About the vCloud Air Platform APIs Additionally, the combination of the vCloud Air Platform APIs and the vCloud API require that a client obtain the version of the vCloud instance and its API version. Specifically, the client must obtain which version of vCloud is supported by a given vCloud instance. vCloud Air might be deployed with more than one version of the vCloud instance. vCloud Air can support multiple versions of the vCloud instance.
vCloud Air Platform Programmer's Guide Request: POST https://vchs.vmware.com/api/vchs/sessions Authorization: Basic UserName@domain.com:password Accept: application/xml;version=5.6 Wherein UserName@domain.com:password is encoded. Response: 201 Created x-vchs-authorization:vchs-auth-token Authorization with vCloud Air and vCloud All requests from authenticated clients must include an Authorization header. The response code indicates whether the request succeeded or how it failed.
Chapter 1 About the vCloud Air Platform APIs n Creates a virtual machine by using a template, powers on the virtual machine, and obtain its IP address for subsequent connections. Then, runs a Web service on that virtual machine. To run this code sample, you must log in as a user assigned to one or more of the following roles: Virtual infrastructure administrator or End User.
vCloud Air Platform Programmer's Guide 14 VMware, Inc.
Hello vCloud Air : A RESTful Workflow 2 vCloud Air clients and servers communicate over HTTPS, exchanging XML representations of vCloud API objects. This simplified example of a RESTful workflow includes logging in to vCloud Air, requesting service details from vCloud, and creating a vCloud session to obtain the list of virtual data centers for that compute service.
vCloud Air Platform Programmer's Guide The Session element, which the API returns from a successful login, contains a link to the services for that vCloud Air account. The client invokes the service link and receives a list of services. Each service contains a serviceType, serviceId, and an href to the content for that service.
Chapter 2 Hello vCloud Air : A RESTful Workflow serviceType="compute:type" type="application/xml;class=vnd.vmware.vchs.compute" href="https://vchs.vmware.com/api/vchs/compute/compute-uuid" /> Example: Requests and Responses to Log in to Your Services This example shows the two parts that are required for logging in to the Compute Service that you have subscribed to with vCloud Air.
vCloud Air Platform Programmer's Guide serviceType="compute:dedicatedcloud" type="application/xml;class=vnd.vmware.vchs.compute" href="https://vchs.vmware.com/api/vchs/compute/vchs-2" /> Create a Session for a Virtual Data Center in a Service When you log in to vCloud Air, you retrieve the Services element, which contains elements for each Compute Service your company has purchased for vCloud Air. Each Service element in the list contains a reference to the service.
Chapter 2 Hello vCloud Air : A RESTful Workflow 3 Create a session to the virtual data center by issuing a POST request to the URL in the Vdc element for that virtual data center: POST href=https://vchs.vmware.com/api/vchs/compute/compute-uuid/vdc/vdc-uuid/vcloudsession The returned response includes the session for the virtual data center: PAGE 20vCloud Air Platform Programmer's Guide Example: Requests and Responses to Create a Session for a Virtual Data Center This example shows the five parts (requests and responses) that are required to create a session for a virtual data center located in a vCloud instance. This example shows a request and response for a Dedicated Cloud service, with the auto assigned ID 3786bb05-dc9a-471b-91cd-554499d45629, that contains a reference to one virtual data center named 0001example-vdc-1-public-api.
Chapter 2 Hello vCloud Air : A RESTful Workflow name="0001-example-vdc-1-public-api" type="application/xml;class=vnd.vmware.vchs.vcloudsession" href="https://vchs.vmware.com/api/vchs/compute/vchs-2/vdc/vdc-7/vcloudsession" /> Request 3: POST href=https://vchs.vmware.com/api/vchs/compute/vchs-2/vdc/vdc-7/vcloudsession Accept: application/xml;version=5.6 Response 3: 201 Created
vCloud Air Platform Programmer's Guide type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud-examplehost1.example.com/api/vdc/vdc-7" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 https://vcloud.example.com/api/v1.5/schema/master.xsd"> PAGE 23
Chapter 2 Hello vCloud Air : A RESTful Workflow 20 0 0 true Log Out To log out and end a vCloud Air session, delete the session you created when you logged in.
vCloud Air Platform Programmer's Guide 24 VMware, Inc.
Index A V Authorization header 23 Authorization response codes 11 vCloud Air authorization token 15 common workflows 12 delete session 23 platform APIs 7 RESTful workflow 15 user credentials 11, 15 vCloud Air Extensions, user roles 11 vCloud Air Platform APIs, version 10 vCloud API authorization token 18 endpoints 7 session 8, 18 session example code 12 session token 7 user roles 11 version 10, 18 XML representations 15 vdcref 18 virtual data center attributes 18 reference 18 UUID 18 VMware Developer Co
vCloud Air Platform Programmer's Guide 26 VMware, Inc.
