VMware vCloud Air OnDemand - 5.7 Programmer's Guide

vCloud Air Platform Programmer's

Guide

vCloud Air OnDemand 5.7

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-001712-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:

[e-mail]

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

About the vCloud Air Platform APIs 7

1

The VMware APIs for Virtual Private Cloud OnDemand 8

Service-Oriented Architecture Explained 8

About Plans, Instances, and the Compute Service 9

Media Support - JSON and XML 11

API Versioning 12

Authentication and Authorization 12

Roles for the APIs for Cloud Automation 13

Error Codes and Error Handling 13

Filter Expressions 15

vCloud Air Platform APIs Schema Reference 15

About the Examples in This Programmer's Guide 16

Hello vCloud Air: A Simplified RESTful Workflow 17

2

Log In and Receive Access Token 18

List Available Plans and Instances 19

Managing Users 23

3

About User Management 23

List Users 25

Add a User 28

Update a User 30

Delete a User 33

Retrieve Forgotten Password 34

Metering and Billing for Resource Usage 37

4

About Resource Usage Metering and Billing 37

Workflow for Using the Metering GET Operations 38

Summary of Metering and Billing Requests 39

Index 41

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 APIs for vCloud Air
Virtual Private Cloud OnDemand (formerly known as the vCloud Air API Extensions).

VMware provides many different APIs and SDKs for applications and goals. This guide provides
information about vCloud Air Platform APIs for developers who create RESTful clients for vCloud Air
Virtual Private Cloud OnDemand.

Intended Audience

This guide is intended for software developers who are building interactive clients of vCloud Air
Virtual Private Cloud OnDemand. 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 Documentation

The vCloud Air – Virtual Private Cloud OnDemand User's Guide and the vCloud Air Compute Service

Programming Guide (API Version 9.0) contain detailed information about many of the objects and

operations referred to in this guide.

VMware Technical Publications Glossary

VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions
of terms as they are used in VMware technical documentation, go to

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

VMware, Inc.

5

vCloud Air Platform Programmer's Guide

6 VMware, Inc.

About the vCloud Air Platform APIs 1

The vCloud Air Platform APIs provide programmatic access to vCloud Air
Virtual Private Cloud OnDemand.

Virtual Private Cloud OnDemand is an infrastructure-as-a-service (IaaS) platform that allows customers to
consume specific compute, storage, and networking resources as incremental pay-as-you-go services.
Virtual Private Cloud OnDemand leverages a resource pool-based delivery model. Customers pay for only
the resources they actually used, on a metered, charge-back basis, under flexible service agreements, as
opposed to fixed-term contracts. Customers can increase or decrease capacity based on demands and
budget.

Customers consume Virtual Private Cloud OnDemand like any software-defined data center. Because
Virtual Private Cloud OnDemand is built on the vSphere and vCloud platforms, customers consume it the
same way that they consume their existing on-premises vSphere environments.

For more information about the features of vCloud Air – Virtual Private Cloud OnDemand, see Introducing

Virtual Private Cloud OnDemand in the vCloud Air – Virtual Private Cloud OnDemand User's Guide.

This chapter includes the following topics:

“The VMware APIs for Virtual Private Cloud OnDemand,” on page 8

n

“Service-Oriented Architecture Explained,” on page 8

n

VMware, Inc.

“About Plans, Instances, and the Compute Service,” on page 9

n

“Media Support - JSON and XML,” on page 11

n

“API Versioning,” on page 12

n

“Authentication and Authorization,” on page 12

n

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

n

“Error Codes and Error Handling,” on page 13

n

“Filter Expressions,” on page 15

n

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

n

“About the Examples in This Programmer's Guide,” on page 16

n

7

Schema Docs

Network

Compute

Metering

Identity
Management

Service
Controller

REST API

vCloud Air

vCloud Air Platform Programmer's Guide

The VMware APIs for Virtual Private Cloud OnDemand

The vCloud Air Platform APIs provides 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.

Customers manage and consume Virtual Private Cloud OnDemand resources by using public APIs. The
public APIs provide management of cloud resources including virtual data center management,
configuration of network services, and virtual machine instance lifecycle management, as well as access to
resource usage metrics.

Complete programmatic access to the VMware APIs for Virtual Private Cloud OnDemand is accomplished
by utilizing the following VMware APIs:

vCloud Air Platform APIs, version 5.7: Build client applications that discover and access vCloud Air

n

services (such as Virtual Private Cloud OnDemand), manage users for
Virtual Private Cloud OnDemand, and automate resource usage metering and billing.

In addition to this guide, see the vCloud Air Platform APIs Schema Reference , 5.7.

vCloud Air Compute Service APIs: Build client applications that access the API endpoint for the

n

vCloud Compute Service, which exposes compute (vRAM and vCPU resources for virtual machines),
storage, and networking functionality in the public cloud on a pay-as-you-go basis.

For information, see the following documentation:

vCloud Air Compute Service Programming Guide (API Version 9.0)

n

vCloud API 9.0 Schema Reference

n

Service-Oriented Architecture Explained

The vCloud Air Platform APIs are designed to work with the service-oriented architecture on which
Virtual Private Cloud OnDemand is built.

Understanding the service-oriented architecture is essential to creating API clients to automate operations.

The extensibility of the service-oriented architecture supports the discovery and consumption of services
through public APIs, allowing for a common framework, and loosely-coupled services based on a common
message bus.

Figure 1‑1. Components of the Service-Oriented Architecture

8 VMware, Inc.

Chapter 1 About the vCloud Air Platform APIs

Table 1‑1. API Surfaces for Virtual Private Cloud OnDemand

Component Capabilities API URI

Identify
Management

Service Controller

Metering Service Metering data collection and aggregation with an

Compute Service Exposure of compute (vRAM and vCPU resources for

Networking Service The pay-as-you-go network services—gateways,

Authentication and single sign on between

n

services

User identity lifecycle management

n

Authorization, such as access control

n

For information about the APIs for authentication and
authorization, see Chapter 2, “Hello vCloud Air: A

Simplified RESTful Workflow,” on page 17.

For information about the APIs for user management,
see Chapter 3, “Managing Users,” on page 23.

vCloud Air plan and instance management,

n

including the instance lifecycle

Exposure of the service-oriented architecture that

n

is available for consumption

Discovery of plans and instances by customers

n

Registry for information related to plans and

n

instances

For information about the APIs for the Service
Controller, see Chapter 2, “Hello vCloud Air: A

Simplified RESTful Workflow,” on page 17.

interface to your My VMware account for billing data

For information about the APIs for the Metering
Service, see Chapter 4, “Metering and Billing for

Resource Usage,” on page 37.

virtual machines), storage, and networking
functionality in the public cloud on a pay-as-you-go
basis

For information about the APIs for the vCloud
Compute Service, see vCloud Air Compute Service

Programming Guide (API Version 9.0).

networks, vApp/VM networks, firewall and NAT
rules

For information about the APIs for the Networking
Service, see Network Administration in the vCloud Air
Compute Service Programming Guide.

NOTE External networks and network pools are
system resources managed by vCloud Air
administrators with VMware or your authorized
service provider.

/api/iam/login
/api/iam/Users

/api/sc/plans
/api/sc/instances

/api/metering
/api/billing

/api/compute

For the list of API surfaces for
provisioning within the vCloud
Compute Service, see Summary of

vCloud API Provisioning Requests in the

vCloud Air Compute Service Programming
Guide (API Version 9.0).

/api/admin/edgeGateway
/api/admin/vdc/id/networks

About Plans, Instances, and the Compute Service

To work with the service-oriented architecture on which Virtual Private Cloud OnDemand is built, you
need to understand the following resources and how they interact.

Plans

n

VMware, Inc. 9

vCloud Air Platform Programmer's Guide

A plan abstracts the infrastructure and platform functionality for Virtual Private Cloud OnDemand.
You can think of a plan as a template because it defines how you consume resources provided in the
VMware public cloud. For example, the plan for Virtual Private Cloud OnDemand allows customers to
create virtual machines configured with 2.6GHz vCPUs. Other plans for vCloud Air might allow
customers to create virtual machines configured with a different vCPU speed.

NOTE Each location can have different plans provisioned; if multiple locations are offering the same
plan, the plans in each location have the same plan name.

For information about how Virtual Private Cloud OnDemand is available in different locations, see

Geographical Locations in the vCloud Air – Virtual Private Cloud OnDemand User's Guide.

Instances

n

An instance is a consumable instance of a given plan. After account creation, you initialize an instance
in a chosen location.

Compute Service

n

A user in vCloud Air can access the vCloud API through the vCloud Compute Service. The vCloud
Compute Service is the service that exposes the compute, networking, and storage functionality that is
available to customers of Virtual Private Cloud OnDemand.

For information about the APIs to develop client applications that access the API endpoint for the
vCloud Compute Service, see the vCloud Air Compute Service Programming Guide (API Version 9.0).

A plan, which is a complex type, has the following structure:

<xs:element name="Plan" type="service:PlanType"/>
<xs:complexType name="PlanType">
<xs:complexContent>
<xs:extension base="common:ResourceType">
<xs:sequence>
<xs:element name="region" type="common:NonEmptyString"/>
<xs:element name="description" type="common:NonEmptyString" minOccurs="0"/>
<xs:element name="planVersion" type="common:NonEmptyString"/>
<xs:element name="planAttributes" type="common:NonEmptyString" minOccurs="0"/>
<xs:element name="instanceSpec" type="common:NonEmptyString" minOccurs="0"/>
<xs:element name="planPolicy" type="service:PlanPolicyType" minOccurs="0"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="PlanList" type="service:PlanListType"/>
<xs:complexType name="PlanListType">
<xs:sequence>
<xs:element name="plans" type="service:PlanType" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>

An instance has the following (complex type) structure:

<xs:element name="Instance" type="instance:InstanceType"/>
<xs:complexType name="InstanceType">
<xs:complexContent>
<xs:extension base="common:ResourceType">
<xs:sequence>
<xs:element name="description" type="common:NonEmptyString" minOccurs="0"/>
<xs:element name="region" type="common:NonEmptyString"/>
<xs:element name="serviceName" type="common:NonEmptyString"/>

10 VMware, Inc.

Chapter 1 About the vCloud Air Platform APIs

<xs:element name="instanceVersion" type="common:NonEmptyString" minOccurs="0"/>
<xs:element name="planId" type="common:NonEmptyString"/>
<xs:element name="serviceGroupId" type="common:NonEmptyString"/>
<xs:element name="apiUrl" type="xs:anyURI"/>
<xs:element name="dashboardUrl" type="xs:anyURI"/>
<xs:element name="instanceAttributes" type="common:NonEmptyString" minOccurs="0"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>

The instance, as shown in the example, has the following attributes:

serviceName: The name of the service offering for the plan

n

The serviceName attribute can be used to distinguish whether a plan or instance belongs to the Compute
Service or another vCloud Air service.

planId: The plan associated with the creation of an instance

n

serviceGroupId: Service group ID associated with the creation of the instance

n

When you sign up for Virtual Private Cloud OnDemand, VMware creates your account and assigns a
service group ID to your account. VMware uses your service group ID as part of its billing system. The
service group ID indicates which billing account to charge for resource usage.

Each instance created for Virtual Private Cloud OnDemand contains one vCloud Compute Service. The
vCloud Compute Service exposes compute (vRAM and vCPU resources for virtual machines), storage, and
networking functionality in the public cloud on a pay-as-you-go basis.

Media Support - JSON and XML

The vCloud Air Platform APIs support XML and JSON data input and output formats. Whether you specify
JSON or XML in a request, the data structure returned in the response is equivalent for both formats; the
only difference is the data encoding differs by format.

Request Headers

In HTTP requests, API clients must specify in the Content-Type header the format in which data is
submitted:

Content-Type: application/xml
Content-Type: application/json

For HTTP responses, specifying the media type and subtype is optional.

For HTTP responses, the vCloud Air Platform APIs support specifying in the Accept header the following
media types and subtypes:

Accept: application/xml
Accept: application/json
Accept: application/*
Accept: */*

When you do not specify a media type or subtype or you specify wildcards in an Accept header, the
vCloud Air Platform APIs provide the HTTP response by using application/xml. To receive a response
using JSON, you must explicitly specify application/json in the Accept header.

VMware, Inc. 11

vCloud Air Platform Programmer's Guide

Table 1‑2. Media Type and Subtype Support

Type Media Range

Application media type and JSON subtype Accept:application/json;class=mediatype

Application media type and XML subtype Accept:application/xml;class=mediatype

Wildcard media type and subtype

API Versioning

The vCloud Air Platform APIs follow an API version scheme to ensure standardization throughout the API
surface and to provide backward compatibility with future releases.

To specify the API version for content negotiation, include the vCloud Air Platform APIs version in the

Accept header as an extension parameter (;version=5.7).

The API versions the entire information model except for the media classes. (The media class for a resource
is optional and does not include versioning information.)

Accept:application/*;class=mediatype

n

Accept: */*;class=mediatype

n

Media type defaults to “application”

n

Subtype defaults “xml”

n

NOTE Specifying the media class for a resource is optional
and does not include versioning information.

NOTE

If you specify version=* in the Accept header, the API uses the latest API version.

n

When omitting the version from the Accept header, the API performs the operations by using the most

n

recent API version supported for the vCloud Air Platform APIs.

In HTTP responses, the API returns the version in the Content-Type header as an extension parameter.

Authentication and Authorization

HTTP communications between vCloud Air clients and servers are secured with SSL. In addition to SSL
encryption, vCloud Air implements authentication and authorization for secure API access.

Authentication with vCloud Air

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 sends a user
name and password as basic credentials in MIME Base64 encoding:

Authorization: Basic [e-mail]:password

The vCloud Air Identity Management Service authenticates the user credentials for
Virtual Private Cloud OnDemand and returns an OAuth 2.0 Access token that is signed and formatted using
Base64 encoded JSON.

Response:

201 Created
vchs-authorization:vchs-OAuth-token

NOTE Before you can receive an OAuth token in a response, you must log in to
Virtual Private Cloud OnDemand using the Web UI and accept the Terms of Service.

12 VMware, Inc.

Chapter 1 About the vCloud Air Platform APIs

Authorization with vCloud Air and vCloud

The returned OAuth token contains the necessary user attributes, such as user name, user ID, company
name, company ID, and user permissions, for API clients to access each functional boundary surfaced by the
API and to receive an authorization token from vCloud.

All requests from clients must include the OAuth token the Authorization header:

Authorization: Bearer OAuth_token

After the client authenticates, vCloud Air retrieves a SAML session token (x-vcloud-authorization) and
authenticates with the vCloud instance to perform Compute Service operations.

The response codes indicate whether requests succeeded or how they failed. When a request is successful,
the server returns HTTP response code 201 Created because logging in to the API requires a POST call. If an

Authentication header is missing, the server returns HTTP response code 403. If the credentials supplied in

an Authentication header are invalid, or if the token has expired, the server returns HTTP response code

401.

NOTE OAuth tokens expire 15 minutes after their issue times (even when API clients are active). You cannot
revoke OAuth tokens. If an API client's session terminates and the OAuth token has expired, the client must
re-authenticate with a user name and password.

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 in vCloud Air, see Role-based User

Account Management in the vCloud Air Virtual Private Cloud OnDemand User's Guide.

The following roles have access to the vCloud Air API:

Virtual Infrastructure Administrator – allows management of virtual data centers, virtual machines,

n

and backup settings

Read-only Administrator – read access to all administration objects

n

End User role – read and write access to virtual machines

n

These vCloud Air roles map to the following roles in the vCloud API for the Compute Service as follows:

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

vCloud Air vCloud API for the Compute Service

Virtual Infrastructure Administrator VPC Administrator

Read-Only Administrator Read-Only VPC Administrator

End User VPC User

Each of the vCloud API roles—VPC Administrator, Read-Only VPC Administrator, and VPC User—provide
access to vCloud functionality. For the access list for each of the vCloud API roles, see vCloud Air Roles and

vCloud Director Rights in the vCloud Air Compute Service Programming Guide.

Error Codes and Error Handling

The following API functional boundaries for vCloud Air are designed to use standardized error handling:

Identity Management Service (IAM)

n

Service Controller (SC)

n

VMware, Inc. 13