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.
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 Virtual Private Cloud OnDemand 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 8 2 H
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.
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.
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.
Chapter 1 About the vCloud Air Platform APIs Table 1‑1. API Surfaces for Virtual Private Cloud OnDemand Component Capabilities API URI Identify Management n Authentication and single sign on between services n User identity lifecycle management n Authorization, such as access control For information about the APIs for authentication and authorization, see Chapter 2, “Hello vCloud Air: A Simplified RESTful Workflow,” on page 17.
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.
Chapter 1 About the vCloud Air Platform APIs The instance,
vCloud Air Platform Programmer's Guide Table 1‑2.
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.
vCloud Air Platform Programmer's Guide n Metering Service (M/B) For information about the errors returned by the Compute Service, see vCloud API REST Responses in the vCloud Air Compute Service Programming Guide.
Chapter 1 About the vCloud Air Platform APIs Filter Expressions You can filter results using string matching or numeric comparison operations. A filter comprises one or more subexpressions drawn from the following set of operators. When using filtering with the API, the following conditions apply: n All collection APIs use standardized filtering. n Only one query parameter is supported for filtering named as "filter".
vCloud Air Platform Programmer's Guide 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. 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, user management, and obtaining metering data for resource usage.
Hello vCloud Air: A Simplified RESTful Workflow 2 vCloud Air clients and servers communicate over HTTPS, exchanging XML or JSON representations of vCloud API objects for the Compute Service. This simplified example of a RESTful workflow includes logging in to Virtual Private Cloud OnDemand and requesting service details from the Service Controller.
vCloud Air Platform Programmer's Guide Log In and Receive Access Token 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. Figure 2‑1. Log in and Accept Terms of Service Sequence Diagram IAM Client POST api/iam/login alt Authentication failed Response 401 unauthorized Response 412 TOS not accepted Success & TOS accepted Store SAML token in database Generate OAuth 2.
Chapter 2 Hello vCloud Air: A Simplified RESTful Workflow Response HTTP/1.1 201 Created Header: Content-Type: application/json;version=5.7 vchs-authorization: eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJmOTF… Body: {"serviceGroupIds":["89a6da00-0d15-48e9-8fed-6c87dfca5c0e"]} List Available Plans and Instances To programmatically access the vCloud Compute Service, you must discover the plans and instances available in Virtual Private Cloud OnDemand. Figure 2‑2.
vCloud Air Platform Programmer's Guide In the request, include the OAuth token: Authorization: Bearer OAuth_token Include the OAuth token in all subsequent API requests as a request header. The returned response includes the list of plans for your account.
Chapter 2 Hello vCloud Air: A Simplified RESTful Workflow Response – Log in HTTP/1.1 201 Created Header: vchs-authorization: eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJmOTF… Body: {"serviceGroupIds":["37"]} Request Header – Get plans GET https://vca.vmware.com/api/sc/plans Accept: application/json;version=5.7 Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJmOTF… Response body not required. Response Body – Get plans { { "plans": [{ "link": [], "region": "LVG", "serviceName": "com.vmware.vchs.
vCloud Air Platform Programmer's Guide "id": "71", "name": "Virtual Private Cloud OnDemand" }] } 22 VMware, Inc.
3 Managing Users Administrators add users for Virtual Private Cloud OnDemand and assign one or more roles to them. User roles have a default group of privileges. Administrators can manage users and their details.
vCloud Air Platform Programmer's Guide Table 3‑1.
Chapter 3 Managing Users Figure 3‑1.
vCloud Air Platform Programmer's Guide Example: Requests and Responses to List Users This example shows how to request a list of all users for your account and then request details for a specific user. Request Header – List all users GET https://vca.vmware.com/api/IAM/Users Accept: application/json;version=5.7 Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJiN2VjNjUyZi1mZmUzLTRh… Request body not required.
Chapter 3 Managing Users "customerNumber": null, "email": "1925test@sample.com", "familyName": "FamilyName", "givenName": "John", "roles": { "roles": [ { "description": "Allows user management and account settings.", "name": "Account Administrator", "id": "1" } ] }, "serviceGroupIds": { "serviceGroupIds": [] }, "tosAcceptDate": null, "tosAccepted": false, "userName": "1925test@sample.com" } ] } Request Header – Get user GET https://vca.vmware.
vCloud Air Platform Programmer's Guide "tosAcceptDate": null, "tosAccepted": false, "userName": "test994@sample.com" } Add a User You can add users and assign privileges to them in Virtual Private Cloud OnDemand. The company attribute is present in the OAuth token vCloud Air that sends as a part of the Authorization header. The new user is created using the company value of the administrator who logged in to create the user.
Chapter 3 Managing Users Table 3‑3.
vCloud Air Platform Programmer's Guide "schemas": [ "urn:scim:schemas:core:1.0" ], "state": "Active", "id": "7179ba2e-6d49-485f-b54e-16e3b8ea3058", "companyId": "422ca48d-a8e6-4b71-9f8f-5aa78362f98e", "customerNumber": null, "email": "test12345@sample.com", "familyName": "test12345", "givenName": "Jill", "roles": { "roles": [ { "description": "Allows creation and management of VMs.
Chapter 3 Managing Users n companyId n userId n tosAccepted n tosAcceptDate n Meta fields n Schema field Prerequisites n You have signed up and registered for Virtual Private Cloud OnDemand and received an email with a user name and password for an Account Administrator. n Using the URL in the confirmation email, you have logged in to Virtual Private Cloud OnDemand using the Web UI, set your password, and accepted the Terms of Service.
vCloud Air Platform Programmer's Guide Request Header – Get userId 790ee208-6c7d-4177-b6c6-212bdbe1a66b GET https://vca.vmware.com/api/iam/Users/790ee208-6c7d-4177-b6c6-212bdbe1a66b Accept: application/json;version=5.7 Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJiN2VjNjUyZi1mZmUzLTRh… Request body not required. Response Body – Get userId 790ee208-6c7d-4177-b6c6-212bdbe1a66b {"users":[ "meta": { "created":1402527010108, "modified":1402527010108 }, "schemas": [ "urn:scim:schemas:core:1.
Chapter 3 Managing Users "id": "790ee208-6c7d-4177-b6c6-212bdbe1a66b", "companyId": "e9b1f777-ab16-493d-a0af-ad3474e13cd2", "customerNumber": null, "email": "test994@sample.com", "familyName": "newName", "givenName": "Jane", "roles": { "roles": [ { "description": "Allows creation and management of VMs.", "name": "Account Administrator", "id": "6" } ] }, "serviceGroupIds": { "serviceGroupIds": [] }, "tosAcceptDate": null, "tosAccepted": false, "userName": "test994@sample.
vCloud Air Platform Programmer's Guide Procedure 1 If necessary, issue a request to get the ID for the user who you want to delete: GET https://vca.vmware.com/api/iam/Users In the request, include the OAuth token and the Accept header: Accept: application/json;version=5.7 Authorization: Bearer OAuth_token Include the OAuth token in all subsequent API requests as a request header. The returned response includes the list of users for your account.
Chapter 3 Managing Users Include the OAuth token in all subsequent API requests as a request header. The returned response includes elements for the specified users. 2 Issue a request to send a link to reset the user password: PUT https://vca.vmware.com/api/iam/Users/userName/password/forgot Accept: application/json;version=5.7 Authorization: Bearer OAuth_token Example: Request and Response to Retrieve Forgotten Password Request Header – Retrieve password PUT https://vca.vmware.
vCloud Air Platform Programmer's Guide 36 VMware, Inc.
Metering and Billing for Resource Usage 4 With Virtual Private Cloud OnDemand, customers pay nothing up front. They pay for only the services they actually used, on a metered, charge-back basis, under flexible service agreements, as opposed to fixed-term contracts. You can use the vCloud Air Platform APIs to retrieve read-only information about current unbilled resource usage and billed usage for Virtual Private Cloud OnDemand.
vCloud Air Platform Programmer's Guide – L1 Primary container for a metered entity; a virtual machine or a gateway in the Compute Service – Billable Usage Metered resource usage Metered Entities > L2 and L1 Metered entities provide a container for measurements and are directly managed by the Metering Service. The Metering Service defines two abstract containers for metering—L2 and L1. These containers correspond to entities in the Compute Service.
Chapter 4 Metering and Billing for Resource Usage See “Summary of Metering and Billing Requests,” on page 39 for information. Summary of Metering and Billing Requests The vCloud Air Platform APIs include the following GET operations that you can use to retrieve metering and billing information for your Virtual Private Cloud OnDemand account. Table 4‑1.
vCloud Air Platform Programmer's Guide Table 4‑1. Resource Usage API Operations for Virtual Private Cloud OnDemand (Continued) 40 Request Response Parameters GET /api/billing/serviceinstance/{service-instance-id}/l1/{l1id}/billed-usage BillableUsage n GET /api/billing/serviceinstance/{service-instance-id}/l2/{l2id}/billed-usage BillableUsage n start= end= or duration=... n n start= end= or duration=... Description Returns all billed usage for an L1 entity post invoicing.
Index A I Accept header 11, 12 API components 8 Compute Service 8 Compute Service endpoint 9 Networking Service 8 sign-up requirement 17 user roles 13 version 11 audiences, defined 8 authentication, requirements 18 Authentication header, error 13 Authorization header 12, 18 IDs company 23 deleting users 33 instances 19 metering object hierarchy 37 objects 16 plans 19 roles 23 service groups 19 updating users 30 users 23 UUIDs 16 virtual data center 38 virtual machines 38 infrastructure-as-a-service, def
vCloud Air Platform Programmer's Guide R request, errors 13 resources recover from users 33 usage calculation 37 usage metering 37 virtual data center ID, discovery 38 X XMLschema definition files 15 parser 15 S SAML session token 12, 18 schema downloading 15 reference documentation 8 Service Controller API 17 filtering 15 service-oriented architecture, defined 8 serviceGroupIds defined 9 metering requirement 37 serviceName, defined 9 sessions, users terminated 33 SSL encryption 12 string matching 15 T
