Red Hat Enterprise Virtualization 3.3

Developer Guide

Using the Red Hat Enterprise Virtualization Application Programming Interfaces

Legal Notice

Copyright © 2014 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.


This document describes Red Hat Enterprise Virtualization's developer API and SDK.
1. Document Conventions
2. Getting Help and Giving Feedback
I. Introduction
1. Introduction
1.1. Introduction to the Red Hat Enterprise Virtualization REST API
1.2. Representational State Transfer
1.3. Red Hat Enterprise Virtualization REST API Prerequisites
2. Authentication and Security
2.1. TLS/SSL Certification
2.2. HTTP Authentication
2.3. Authentication Sessions
3. REST API Quick Start Example
3.1. REST API Quick Start Introduction
3.2. Example: Access API Entry Point
3.3. Example: List Data Center Collection
3.4. Example: List Host Cluster Collection
3.5. Example: List Logical Networks Collection
3.6. Example: List Host Collection
3.7. Example: Approve Host
3.8. Example: Create NFS Data Storage
3.9. Example: Create NFS ISO Storage
3.10. Example: Attach Storage Domains to Data Center
3.11. Example: Activate Storage Domains
3.12. Example: Create Virtual Machine
3.13. Example: Create Virtual Machine NIC
3.14. Example: Create Virtual Machine Storage Disk
3.15. Example: Attach ISO Image to Virtual Machine
3.16. Example: Start Virtual Machine
3.17. Example: Check System Events
4. Python Quick Start Example
4.1. Python Quick Start Introduction
4.2. Example: Accessing the API Entry Point using Python
4.3. Example: Listing the Data Center Collection using Python
4.4. Example: Listing the Cluster Collection using Python
4.5. Example: Listing the Logical Networks Collection using Python
4.6. Example: Listing the Host Collection using Python
4.7. Example: Approving a Host using Python
4.8. Example: Creating NFS Data Storage using Python
4.9. Example: Creating NFS ISO Storage using Python
4.10. Example: Attaching Storage Domains to a Data Center using Python
4.11. Example: Activating Storage Domains using Python
4.12. Example: Creating a Virtual Machine using Python
4.13. Example: Creating a Virtual Machine NIC using Python
4.14. Example: Creating a Virtual Machine Storage Disk using Python
4.15. Example: Attaching an ISO Image to a Virtual Machine using Python
4.16. Example: Starting a Virtual Machine using Python
4.17. Example: Checking System Events using Python
II. REST Application Programming Interface
5. Entry Point
5.1. Accessing the API Entry Point
5.2. Product Information
5.3. Link Elements
5.4. Special Object Elements
5.5. Summary Element
5.6. RESTful Service Description Language (RSDL)
5.7. Backup-Restore API Overview
5.8. Full Virtual Machine Backups
5.9. Full Virtual Machine Restore
5.10. Red Hat Enterprise Virtualization Windows Guest VSS Support
5.11. QEMU Guest Agent Overview
5.12. VSS Transaction Flow
6. Compatibility Level Versions
6.1. Compatibility Level Versions
6.2. Upgrading Compatibility Levels
7. Capabilities
7.1. Capabilities
7.2. Version-Dependent Capabilities
7.3. Current Version
7.4. Features
7.5. CPUs
7.6. Power Managers
7.7. Fence Types
7.8. Storage Types
7.9. Configuration Types
7.10. Storage Domain Types
7.11. Virtual Machine Types
7.12. Boot Devices
7.13. Display Types
7.14. NIC Interface Types
7.15. OS Types
7.16. Disk Formats
7.17. Disk Interfaces
7.18. Virtual Machine Affinities
7.19. Custom Properties
7.20. Boot Protocols
7.21. Error Handling
7.22. Storage Formats
7.23. Creation States
7.24. Power Management States
7.25. Host States
7.26. Host Non-Operational Details
7.27. Network States
7.28. Storage Domain States
7.29. Template States
7.30. Virtual Machine States
7.31. Virtual Machine Pause Details
7.32. Disk States
7.33. Host Network Interface Card States
7.34. Data Center States
7.35. Virtual Machine Device Types
7.36. Watchdog Models
7.37. Watchdog Actions
7.38. Gluster Volume Types
7.39. Gluster Transport Types
7.40. Permits
7.41. Scheduling Policies
7.42. Usages
7.43. NFS Versions
7.44. Power Management Proxy Types
7.45. CPU Modes
7.46. SCSI Generio I/O Options
7.47. Authentication Methods
7.48. Step Types
7.49. Payload Encodings
7.50. Gluster Volume Types
7.51. Transport Types
7.52. Gluster Volume States
7.53. Brick States
7.54. Reported Device Types
7.55. IP Versions
7.56. Snapshot Status
7.57. Content Types
7.58. Hook States
7.59. Stages
8. Common Features
8.1. Element Property Icons
8.2. Representations
8.3. Collections
8.4. Resources
9. Data Centers
9.1. Data Center Elements
9.2. XML Representation of a Data Center
9.3. Methods
9.4. Sub-Collections
9.5. Actions
10. Host Clusters
10.1. Host Cluster Elements
10.2. Memory Policy Elements
10.3. Scheduling Policy Elements
10.4. XML Representation of a Host Cluster
10.5. Methods
10.6. Sub-Collections
11. Networks
11.1. Network Elements
11.2. XML Representation of a Network Resource
11.3. Methods
11.4. Sub-collections
12. Storage Domains
12.1. Storage Domain Elements
12.2. XML Representation of a Storage Domain
12.3. Methods
12.4. Storage Types
12.5. Export Storage Domains
12.6. Sub-Collections
12.7. Actions
13. Storage Connections
13.1. Storage Connection Elements
13.2. XML representation of a Storage Connection Resource
13.3. Methods
14. Hosts
14.1. Host Elements
14.2. XML Representation of a Host
14.3. Power Management Elements
14.4. Memory Management Elements
14.5. Methods
14.6. Sub-Collections
14.7. Actions
15. Virtual Machines
15.1. Virtual Machine Elements
15.2. XML Representation of a Virtual Machine
15.3. Methods
15.4. Sub-Collections
15.5. Actions
16. Floating Disks
16.1. Floating Disk Elements
16.2. XML Representation of a Floating Disk
16.3. Methods
16.4. Sub-Collections
17. Templates
17.1. Virtual Machine Template Elements
17.2. XML Representation of a Virtual Machine Template
17.3. Methods
17.4. Actions
18. Virtual Machine Pools
18.1. Virtual Machine Pool Elements
18.2. XML Representation of a Virtual Machine Pool
18.3. Methods
18.4. Actions
19. Domains
19.1. Domain Elements
19.2. XML Representation of a Domain Resource
19.3. Sub-Collections
20. Groups
20.1. Imported Group Elements
20.2. XML Representation of a Group Resource
20.3. Adding a Group from a Directory Service
21. Roles
21.1. Role Elements
21.2. XML Representation of the Roles Collection
21.3. Methods
21.4. Roles Permits Sub-Collection
22. Users
22.1. User Elements
22.2. XML representation of a User Resource
22.3. Methods
23. Tags
23.1. Tag Elements
23.2. XML Representation of a Tag Resource
23.3. Associating Tags
23.4. Parent Tags
24. Events
24.1. Event Elements
24.2. XML Representation of the Events Collection
24.3. XML Representation of a Virtual Machine Creation Event
24.4. Searching Events
24.5. Paginating Events
III. Python Sofware Development Kit
25. Software Development Kit Overview
25.1. Introduction to the Red Hat Enterprise Virtualization Software Development Kit
25.2. Software Development Kit Prerequisites
25.3. Installing the Software Development Kit
26. Using the Software Development Kit
26.1. Connecting to the API using Python
26.2. Resources and Collections
26.3. Retrieving Resources from a Collection
26.4. Retrieving a Specific Resource from a Collection
26.5. Retrieving a List of Resources from a Collection
26.6. Adding a Resource to a Collection
26.7. Updating a Resource in a Collection
26.8. Removing a Resource from a Collection
26.9. Handling Errors
27. Python Reference Documentation
27.1. Python Reference Documentation
IV. Java Software Development Kit
28. Software Development Kit Overview
28.1. Java Software Development Kit Introduction
28.2. Downloading the Java Software Development Kit
29. Using the Software Development Kit
29.1. Connecting to the Red Hat Enterprise Virtualization Manager
29.2. Listing Entities
29.3. Modifying the Attributes of Resources
29.4. Getting a Resource
29.5. Adding Resources
29.6. Performing Actions on Resources
29.7. Listing Sub-Resources
29.8. Getting Sub-Resources
29.9. Adding Sub-Resources to a Resource
29.10. Modifying Sub-Resources
29.11. Performing Actions on Sub-Resources
29.12. Java SDK Best Practices
29.13. Working with SSL (Secure Socket Layer)
A. API Usage with cURL
A.1. API Usage with cURL
A.2. Installing cURL
A.3. Using cURL
A.4. Examples
B. UI Plugins
B.1. Installing Red Hat Support Plugin
C. Certificates
C.1. Creating SSL/TLS Certificates
C.2. Creating an SSL Certificate
C.3. Configuring HTTPS Communication
C.4. Network Security Services (NSS) Database
C.5. Java Keystores
D. Enumerated Value Translation
D.1. Enumerated Value Translation
E. Event Codes
E.1. Event Codes
F. Timezones
F.1. Timezones
G. Revision History