VMware vCloud Air - 5.6 Programmer's Guide

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.

EN-001371-00

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

VMware, Inc.

3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com

2 VMware, Inc.

About this Programmer's Guide 5

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

Hello vCloud Air : A RESTful Workflow 15

Create a Session for a Virtual Data Center in a Service 18

Log Out 23

Index 25

VMware, Inc. 3

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.

Intended Audience

This guide is intended for software developers who are building interactive clients of vCloud Air. This guide discusses Representational State Transfer (REST) and RESTful programming conventions, and vCloud Air technology. You must be familiar with these and other widely deployed technologies such as XML, HTTP, and the Windows or Linux operating system.

Related Publications

The vCloud Air User's Guide and vCloud API Programmer's Guide contain detailed information about many of the objects and operations referred to in this guide.

VMware, Inc.

To access the current versions of these and other VMware books, go to

http://www.vmware.com/support/pubs.

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.

This chapter includes the following topics:

“The VMware APIs for Cloud Automation,” on page 7

“XML Namespace Identifiers,” on page 8

“Overview of Object Types,” on page 8

“Link Relationships in the Object Types,” on page 9

“API Versioning,” on page 10

“Roles for the APIs for Cloud Automation,” on page 11

“Authentication and Authorization,” on page 11

“vCloud Air Platform APIs Schema Reference,” on page 12

“Java Code Samples for Cloud Automation,” on page 12

“About the Examples in this Programmer's Guide,” on page 13

The VMware APIs for Cloud Automation

Programmatic access to the subscription services of vCloud Air consists of consuming the vCloud Air Platform APIs and Compute Service accessed through the vCloud API. The combination of these two APIs provides a single, logical API endpoint for automation of cloud interactions.

The vCloud Air includes calls to log in and get the details of available virtual data centers. The responses to these calls include vCloud endpoints and the vCloud session token. With those credentials, customers can call the vCloud API without needing to provide the credentials again. Customers can automate their workflows without having to store their credentials on disk or in memory.

The obtained vCloud endpoints and session token allow customers to access the vCloud API across all functional boundaries of the subscribed services in vCloud Air. Subscribed services include compute resources, such as Dedicated Cloud and Virtual Private Cloud. The API calls return links to virtual data center objects, which customers can use for virtual machine lifecycle operations and network service operations.

VMware, Inc.

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:

Overview of Object Types

The vCloud Air Platform APIs define a set of objects common to cloud computing environments. An understanding of these objects is essential to using the APIs.

The following conventions apply to the objects you access through the APIs:

List types follow these conventions; for example, an object named Obj :

Uses ObjListType as the XSD type definition.

Contains objlist in the media type.

Has Objs as the element name.

Top level elements of objects in responses extend from EntityType.

The short versions of objects typically are included in other object responses extended from

ReferenceType.

The following table describes all the object types in the vCloud Air Platform APIs.

Table 1‑1. Object Type Descriptions

Object Type Description Class Value

SessionType

ServiceListType

ServiceType

Provides a return type from a login. Contains a link to retrieve the list of compute services.

Contains a list of services purchased by the requesting customer account. Entries in the list are ServiceType.

Represents a reference to service meta data for vCloud Air. Currently, the ServiceType object type includes Dedicated Cloud and Virtual Private Cloud meta data. ServiceType is a lightweight object, which contains the name, an href to Compute, the type of service (compute:dedicatedcloud or compute:vpc), the serviceId (assigned by VMware when your vCloud Air account is provisioned) and the geographical region of the service (for example, "US

- Santa Clara ").

vnd.vmware.vchs.session

vnd.vmware.vchs.servicelist

vnd.vmware.vchs.service

8 VMware, Inc.

Chapter 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.

VdcReferenceType

VCloudSessionType

Represents a reference to a virtual data center representation on vCloud Air. Contains a link to retrieve a vCloud session for each virtual data center.

Represents a reference to a virtual data center on the vCloud instance. The reference includes the full URL to the vCloud instance and an authorization token corresponding to the requesting customer account. The authorization token must be used to access objects within the scope of the virtual data center and the Organization on the vCloud instance.

vnd.vmware.vchs.compute

vnd.vmware.vchs.vdcref

vnd.vmware.vchs.vcloudsession

Link Relationships in the Object Types

The vCloud Air Platform APIs make extensive use of Link elements to provide references to objects and the actions that they support. These elements are the primary mechanism by which a server tells a client how to access and operate on an object.

vCloud Air creates Link elements in a response, which are read-only for the client. If a request includes a

Link element, the server ignores it.

Attributes of a Link Element

In the XML representation of a vCloud object, each Link element has the following form:

LinkType is used for only up and down links; typically, objects do not extend from LinkType.

The media type is represented in the request as the value of the class attribute:

application/xml;class=type;version=5.6

Where type corresponds to the XML structure returned. All class values start with the string

vnd.vmware.vchs.

Elements and References

The vCloud Air object model contains elements and references within those elements.

Elements References

Session Services

ServiceList Service

VMware, Inc. 9

Client Login

▪ auth token ▪ href ▪ VDC href

VdcLink

VcloudSession

VdcLink

Vcloud VDC

services

service

Session ServiceList

Service

▪ serviceType ▪ serviceId ▪ region ▪ href to content

Compute

▪ serviceType=“compute:dc” ▪ serviceId=<assigned>

VcdRef

▪ name ▪ href ▪ region ▪ link to get vcloudsession

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. Link Relationships in the Object Model

When a client creates a session, the client receives a SessionType response, which contains a link to the services for that vCloud Air account. The client sends a GET request to the service link and receives a list of services. Each service contains a service type, service ID, region, and an href to the service. When the client invokes the service href, the client receives a Compute response that contains the type of service, its service ID, and a list of the virtual data center references. Region refers to a collection of physical data centers that are located in distinctly separate geographic areas. You select a region or regions when you purchase compute services. The virtual data center reference contains a link that you can use to log in to vCloud for the Organization corresponding to the VDCReference.

API Versioning

The schema version of the vCloud Air Platform APIs appears in the values of the xmlns attribute in a response.

The version format contains the major and minor versions of the release. For example, a response that used schema version 5.6 would include the following attributes:

10 VMware, Inc.

xmlns="http://www.vmware.com/vchs/v5.6" xmlns:tns="http://www.vmware.com/vchs/v5.6"

All requests must include an HTTP Accept header that designates the API version that the client supports. The header indicates that the request is for version 5.6 of the vCloud Air Platform APIs to use with the vCloud API. The following formats are valid for the version:

Accept: application/xml;version=5.6 Accept: application/*;version=5.6 Accept: */*;version=5.6

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. A client can access the vCloud instance deployed with vCloud Air regardless of its version. When a client sends a GET Compute request, the client receives a response containing a VCloudSession element, which includes a VdcRef reference. The VdcRef reference includes an href to the virtual data center.

Roles for the APIs for Cloud Automation

vCloud Air includes predefined roles. Each of these roles includes a set of default rights.

For information about the rights available for each predefined role invCloud Air, see User Privileges by

Role.

The following roles have access to the vCloud Air Platform API:

Virtual infrastructure administrator – allows management of virtual data centers, virtual machines, and

backup settings

Read-Only administrator – read access to all administration objects

End User role – read write access

Chapter 1 About the vCloud Air Platform APIs

These vCloud Air roles map the following roles in vCloud API as follows:

Table 1‑2. vCloud Air Roles Mapped to vCloud API Roles

vCloud Air vCloud API – Dedicated Cloud vCloud API – Virtual Private Cloud

Virtual Infrastructure Administrator Dedicated VPC Administrator VPC Administrator

Read-Only Administrator Read-Only VPC Administrator Read-Only VPC Administrator

End User VPC User VPC User

Each of the vCloud API roles—Dedicated VPC Administrator, Read-Only VPC Administrator, and VPC User—provide access to vCloud functionality. See the following VMware Knowledgebase article for the access list for each of the vCloud API roles:

Understanding user roles within VMware vCloud Air (2053484)

Authentication and Authorization

Users authenticate with vCloud Air by supplying credentials established when the vCloud Air user was created. User credentials are authenticated by the identity management system for vCloud Air.

Authenticating with vCloud Air returns a vCloud Air authorization token that the client can use to receive an authorization token from vCloud. The client only needs to present authentication credentials once to access each functional boundary (vCloud Air and vCloud) surfaced by the API.

Authentication with vCloud Air

HTTP communications between a vCloud Air client and server are secured with SSL. vCloud Air implements Basic HTTP authentication, as defined by RFC 2617, which enables a client to authenticate by including an Authorization header in the request. The Authorization header contains the basic credentials in Base64 encoding containing a user name and password.

The authentication for this exchange uses the following format:

VMware, Inc. 11

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. If the request is successful, the server returns HTTP response code 201 Created because logging in to the API requires a POST call. If the Authentication header is missing, the server returns HTTP response code 403. If the credentials supplied in the Authentication header are invalid, or if the token has expired, the server returns HTTP response code 401.

After the client authenticates, vCloud Air retrieves a session token from SAML and authenticates with the vCloud instance.

vCloud Air Platform APIs Schema Reference

The schema reference includes detailed information about the XML representations of all vCloud Air API objects and HTTP requests that operate on those objects.

The API represents objects in a cloud as XML documents in which object properties are contained in elements and attributes that have typed values, and an explicit object hierarchy defined by an XML schema. The schema reference includes reference material for all elements, types, and operations in vCloud Air.

Clients of RESTful Web services must be able to request object representations from the server, parse the server's responses to extract the information contained in the responses, and compose requests that are based on the information extracted from the responses.

vCloud Air uses a validating XML parser that requires elements in XML documents to agree in order and number with the schema. Required elements must appear in requests. All elements that appear in requests must appear in the order established by the schema, and with content that conforms to the type constraint specified in the schema.

The schema reference is available in HTML format in the vCloud Air Documentation Center. See vCloud

Air Platform REST APIs Schema Reference.

The schema reference includes the schema definition files. To download the complete set of schemas for the vCloud Air Platform APIs, see Download an Archive in the vCloud Air Documentation Center.

Java Code Samples for Cloud Automation

In addition to this programmer's guide and the schema reference, VMware provides code samples written in Java that client application developers can use as a model for the common workflows in the automation of cloud interactions.

At a high-level, the code samples provide workflows to write a client that programmatically logs in to vCloud Air and establishes a session with vCloud to manage compute services and virtual resources. VMware provides code samples for three sample client applications:

Queries all existing virtual data centers across all regions in both a customer's Dedicated Cloud and

Virtual Private Cloud. To run this code sample, you must log in as a user assigned to one or more of the following roles: Virtual infrastructure administrator, Read-Only administrator, or End User.

12 VMware, Inc.

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.

Adds a NAT rule to enable external HTTPS requests to a Web service running on a virtual machine in

the virtual data center and adds a firewall rule to prevent all other access. To run this code sample, you must log in as a user assigned to the Virtual infrastructure administrator role.

The code samples support the standard use case wherein a company purchases by logging in to My VMware both Virtual Private Cloud and Dedicated Cloud capacity in different regions of vCloud Air. A vCloud Air Account Administrator logs in to the vCloud Air Web UI to create a user and assign that user to an appropriate access role.

Additionally, the code samples illustrate how to establish a vCloud session, request the vCloud instance version, and set the correct version header.

The code samples are available for download from the VMware Community > VMware Technology Network (VMTN) Forums > VMware Developer > Sample Code at

https://communities.vmware.com/community/vmtn/developer/codecentral.

About the Examples in this Programmer's Guide

The examples in this guide of HTTP requests and responses illustrate the workflow and content that is associated with automating login to vCloud Air and session set up for vCloud to obtain virtual data center information.

Chapter 1 About the vCloud Air Platform APIs

Example request headers follow these conventions:

Header names and values are case-insensitive, and can be submitted or returned in any character case.

Other HTTP headers, such as date, content-length, and server, are omitted because they are not relevant

to the specifics of any example.

The XML version and encoding header <?xml version="1.0" encoding="UTF-8"?> is omitted in

example requests.

Example responses follow these conventions:

Responses show only those elements and attributes that are relevant to the operation being explained.

Ellipses (…) indicate omitted content within responses.

The XML version and encoding header <?xml version="1.0" encoding="UTF-8"?> is omitted in

example responses.

Object IDs shown in href attribute values appear as small integers, for example vchs-2 for compute-uuid

or vdc-7 for vdc-uuid. In the API, object IDs are universal unique identifiers (UUIDs) as defined by RFC 4122, for example f5e185a4-7c00-41f1-8b91-0e552d538101.

VMware, Inc. 13

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.

These examples assume that you have you have subscribed to vCloud Air, have created a user account, and have at least one virtual data center in the Compute Service.

1 Log in to vCloud Air on page 15

vCloud Air requires login requests to be authenticated. Begin the workflow with a login request that supplies user credentials in the MIME Base64 encoding format as specified in RFC 1421.

2 Create a Session for a Virtual Data Center in a Service on page 18

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.

3 Log Out on page 23

To log out and end a vCloud Air session, delete the session you created when you logged in. The logout request, like all other authenticated requests, must include the Authorization header.

Log in to vCloud Air

vCloud Air requires login requests to be authenticated. Begin the workflow with a login request that supplies user credentials in the MIME Base64 encoding format as specified in RFC 1421.

Prerequisites

Your company has purchased Virtual Private Cloud or Dedicated Cloud capacity in different regions of

vCloud Air via My VMware and obtained an Account Administrator login on vCloud Air (procured directly through My VMware).

Your Account Administrator has created at least one user account with credentials in the vCloud Air.

You are a user assigned to a role that can access the API.

You are a user assigned to a role that can access your compute services.

As a vCloud Air client, you present your credentials one time to log in and view the list of your subscribed compute services in vCloud Air.

VMware, Inc.

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. The compute serviceType has the

following values:

compute:dedicatedcloud

compute:vpc

The vCloud Air automated subscription system assigns the value of the serviceId attribute.

Procedure

1 POST a request to this URL that includes your user name and password in a MIME Base64 encoding:

POST https://vchs.vmware.com/api/vchs/sessions

The initial POST requires that you enter the Authorization header with an encoded Base64 username:password value as shown:

Authorization: Basic <HelloUser@example.com:password>

Wherein HelloUser@example.com:password is encoded.

If the request is successful, the server returns the following items in the response:

Response Header: x-vchs-authorization:vchs-auth-token <Session ...> <Link rel="down" type="application/xml;class=vnd.vmware.vchs.servicelist" href="https://vchs.vmware.com/api/vchs/services" /> </Session>

HTTP response code 201 Created

A response that contains the x-vchs-authorization

A response with a Session element that contains a link of type

application/xml;class=vnd.vmware.vchs.servicelist to get your list of subscribed compute

services in vCloud Air

2 From the Session response, use the value from the servicelist link and issue a GET request to retrieve

the list of services:

GET href="https://vchs.vmware.com/api/vchs/services"

3 In the request, include the vCloud Air authorization token:

x-vchs-authorization:vchs-auth-token

Include the x-vchs-authorization token in all subsequent API requests as a request header.

The returned response includes the list of services subscribed for your vCloud Air account. Each

Service element in the list has the following format:

<Services ...> <Service region="xs:string" serviceId="xs:string"

16 VMware, Inc.

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" /> </Services>

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. The first part of the example shows the request and response for HelloUser to log in to vCloud Air at the URL https://vchs.vmware.com/api/vchs/sessions In Request 1, the initial POST requires you enter the Authorization header with an encoded Base64 username:password value.

The second part shows the request and response for HelloUser to pass the authorization token to obtain the compute service list purchased for the user's company account. The service list contains one service for a Dedicated Cloud subscription.

Request 1:

POST https://vchs.vmware.com/api/vchs/sessions Authorization: Basic Vk13YXJlMTIzIQ== Accept: application/xml;version=5.6

Response 1:

201 Created Response Header: x-vchs-authorization:f1c687e31731cc9a5820d233e46ef1dfa131cb45 ... <Session type="application/xml;class=vnd.vmware.vchs.session" href="https://vchs.vmware.com/api/vchs/session" xmlns="http://www.vmware.com/vchs/v5.6" xmlns:tns=http://www.vmware.com/vchs/v5.6 xmlns:xs=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance> <Link rel="down" type="application/xml;class=vnd.vmware.vchs.servicelist" href="https://vchs.vmware.com/api/vchs/services" /> <Link rel="remove" href="https://vchs.vmware.com/api/vchs/session" /> </Session>

Request 2:

GET https://vchs.vmware.com/api/vchs/services Authorization: x-vchs-authorization:f1c687e31731cc9a5820d233e46ef1dfa131cb45 Accept: application/xml;version=5.6

Response 2:

200 OK <Services type="application/xml;class=vnd.vmware.vchs.servicelist" href="https://vchs.vmware.com/api/vchs/services" ...> <Service region="US - Las Vegas" serviceId="example-1101-130711-1"

VMware, Inc. 17

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" /> </Services>

Create a Session for a Virtual Data Center in a Service

Prerequisites

Verify that you are logged in to vCloud Air and assigned to a user role that can access the API.

Invoking the URL for a service reference returns a Compute element. The Compute element includes an attribute for the serviceType and references to all the virtual data centers created within that service.

When the serviceType is a compute:dedicatedcloud, the Compute element has zero or more virtual data centers. When the serviceType is compute:vpc, the Compute element has one virtual data center.

The reference for each virtual data center (VdcRef) contains the virtual data center name and a link to that virtual data center. Each VdcRef also contains a link to retrieve the vCloud session for that virtual data center.

Procedure

1 Using the Service element returned from the request for the service list, issue a GET request to the URL

for the service:

GET https://vchs.vmware.com/api/vchs/compute/compute-uuid

The returned Compute element contains references to the virtual data centers provisioned for that service.

2 Using the VdcRef href, invoke the reference to the virtual data center for which you want to get a

session:

GET href=https://vchs.vmware.com/api/vchs/compute/compute-uuid/vdc/compute-uuid

The returned response contains a reference to retrieve a session for that virtual data center:

<Vdc ...> <Link rel="down" ...> href="https://vchs.vmware.com/api/vchs/compute/compute-uuid/vdc/vdc- uuid/vcloudsession" /> </Vdc>

18 VMware, Inc.

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:

Include the x-vcloud-authorization token in all subsequent API requests as a request header.

4 Issue a GET request to the following URL for the version of the vCloud instance:

GET https://vcloud-examplehost1.vmware.com/api/versions

NOTE You must query the vCloud version before issuing subsequent calls that require setting the correct version header.

The response contains the vCloud version:

<SupportedVersions ... "https://vcloud-examplehost1.vmware.com/api/versions/schema/versions.xsd"> <VersionInfo> <Version>1.5</Version> <LoginUrl>https://vcloud-examplehost1.example.com/api/sessions </LoginUrl> ... </VersionInfo> <VersionInfo> <Version>5.x</Version> <LoginUrl>https://vcloud-examplehost1.example.com/api/sessions </LoginUrl> ... </VersionInfo> </SupportedVersions>

5 Issue a GET request to the URL for the virtual data center session:

GET href=https://vcloud-examplehost1.example.com/api/vdc/vdc-uuid

In the request, include the vCloud authorization token (Step 3) and the vCloud version (Step 4) by using the following format:

Authorization: x-vcloud-authorization:vcloud-auth-token Accept: application/*+xml;version=5.x

The returned response includes the details for the virtual data center. See Response 5 below.

VMware, Inc. 19

vCloud 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. The compute service has UUID vchs-2 and the virtual data center has the UUID vdc-7.

Request 1:

GET https://vchs.vmware.com/api/vchs/compute/vchs-2 Accept: application/xml;version=5.6

Response 1:

200 OK <Compute serviceId="example-1101-130711-1" serviceType="compute:dedicatedcloud" type="application/xml;class=vnd.vmware.vchs.compute" href="https://vchs.vmware.com/api/vchs/compute/vchs-2" ...> <Link rel="up" name="services" type="application/xml;class=vnd.vmware.vchs.servicelist" href="https://vchs.vmware.com/api/vchs/services" /> <VdcRef status="Active" name="0001-example-vdc-1-public-api" type="application/xml;class=vnd.vmware.vchs.vdcref" href="https://vchs.vmware.com/api/vchs/compute/vchs-2/vdc/vdc-7"> <Link rel="down" 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" /> </VdcRef> </Compute>

Request 2:

GET href=https://vchs.vmware.com/api/vchs/compute/vchs-2/vdc/vdc-7 Accept: application/xml;version=5.6

Response 2:

200 OK <Vdc name="0001-example-vdc-1-public-api" type="application/xml;class=vnd.vmware.vchs.vdcref" href="https://vchs.vmware.com/api/vchs/compute/vchs-2/vdc/vdc-7" ...> <Link rel="down"

20 VMware, Inc.

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" /> </Vdc>

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 <VcloudSession name="example-1101-130711-1-session" ...> <VdcLink authorizationToken="d6eFLOqQYfuEn2MJTp7BQ2ISEO+ZYaEgTcqBy8wZQ6js=" authorizationHeader="x-vcloud-authorization" rel="vcloudvdc" name="example-1101-130711-1" href="https://vcloud-examplehost1.example.com/api/vdc/vdc-7" /> </VcloudSession>

Request 4:

GET https://vcloud-examplehost1.vmware.com/api/versions

Response 4:

<SupportedVersions ... "https://vcloud-examplehost1.vmware.com/api/versions/schema/versions.xsd"> <VersionInfo> <Version>1.5</Version> <LoginUrl>https://vcloud-examplehost1.example.com/api/sessions </LoginUrl> ... </VersionInfo> <VersionInfo> <Version>5.6</Version> <LoginUrl>https://vcloud-examplehost1.example.com/api/sessions </LoginUrl> ... </VersionInfo> </SupportedVersions>

Request 5:

GET href="https://vcloud-examplehost1.example.com/api/vdc/vdc-7" authorizationHeader="x-vcloud-authorization" authorizationToken="vcloud-auth-token" Accept: application/*+xml;version=5.6

Response 5:

The response returns a virtual data center object and its attributes.

<Vdc xmlns="http://www.vmware.com/vcloud/v1.5" status="1" name="0001-example-vdc-1-public-api" id="urn:vcloud:vdc:vdc-7"

VMware, Inc. 21

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"> <Link rel="up" type="application/vnd.vmware.vcloud.org+xml" href="vcloud-examplehost1.example.com/api/org/vdc-7" /> <Link rel="down" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud-examplehost1.example.com/api/vdc/vdc-7/metadata" /> <Link rel="add" type="application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml" href="https://vcloud-examplehost1.example.com/api/vdc/vdc-7/action/uploadVAppTemplate" /> <Link rel="add" type="application/vnd.vmware.vcloud.media+xml" href="https://vcloud-examplehost1.example.com/api/vdc/vdc-7/media" /> ... <AllocationModel>ReservationPool</AllocationModel> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocated>1000</Allocated> <Limit>1000</Limit> <Reserved>1000</Reserved> <Used>0</Used> <Overhead>0</Overhead> </Cpu> <Memory> <Units>MB</Units> <Allocated>1024</Allocated> <Limit>1024</Limit> <Reserved>1024</Reserved> <Used>0</Used> <Overhead>0</Overhead> </Memory> </ComputeCapacity> <ResourceEntities /> <AvailableNetworks> <Network type="application/vnd.vmware.vcloud.network+xml" name="0001-example-vdc-1-public-api-default-isolated" href="https://vcloud-examplehost1.example.com/api/network/vdc-7" /> </AvailableNetworks> <Capabilities> <SupportedHardwareVersions> <SupportedHardwareVersion>vmx-04</SupportedHardwareVersion> ... </SupportedHardwareVersions> </Capabilities> <NicQuota>0</NicQuota>

22 VMware, Inc.

Log Out

To log out and end a vCloud Air session, delete the session you created when you logged in. The logout request, like all other authenticated requests, must include the Authorization header.

Prerequisites

Verify that you are logged in.

Procedure

Chapter 2 Hello vCloud Air : A RESTful Workflow

Send a DELETE request specifying the href of the current Session object.

Example: Logout Request and Response

This example deletes the current user's session, which logs the user out.

Request:

DELETE https://vchs.vmware.com/api/vchs/session Type None

Response:

204 No Content

VMware, Inc. 23

vCloud Air Platform Programmer's Guide

24 VMware, Inc.

Index

Authorization header 23 Authorization response codes 11

Base64 encoding 11

class values 9 compute service

attributes 9 meta data 8 region 8

compute services

service element 15 values 15

headers, accept version format 10 HTTP authentication 11

Link element,attributes 9 Link element, object model 9

media type 9

request header, example conventions 13 responses, example conventions 13

SAML authentication 11 schema, downloading 12

Schema, XML namespace 8 Session element, XML namespace 8

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 Community 12 vnd.vmware.vchs 9

XML

version 13

xmlns attribute 10 XMLschema

definition files 12

parser 12 XSD type definition 8

type constraints 12

user roles 12, 15 UUID, virtual data center 18

VMware, Inc.

vCloud Air Platform Programmer's Guide

26 VMware, Inc.

VMware vCloud Air - 5.6 Programmer's Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

About this Programmer's Guide

About the vCloud Air Platform APIs 1

The VMware APIs for Cloud Automation

XML Namespace Identifiers

Overview of Object Types

Link Relationships in the Object Types

API Versioning

Roles for the APIs for Cloud Automation

Authentication and Authorization

vCloud Air Platform APIs Schema Reference

Java Code Samples for Cloud Automation

About the Examples in this Programmer's Guide

Log in to vCloud Air

Create a Session for a Virtual Data Center in a Service

Log Out

Index