Red Hat Enterprise Virtualization 3.0

REST API Guide

Using the Red Hat Enterprise Virtualization Representational State Transfer Application Programming Interface

Edition 1

Red Hat Documentation Team

Red Hat Engineering Services and Operations

Daniel Macpherson

Red Hat Engineering Content Services

David Jorm

Red Hat Engineering Content Services

Mark McLoughlin

Red Hat Engineering

Eoghan Glynn

Red Hat Engineering

Legal Notice

Copyright © 2011 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.

Abstract

This document describes the Representational State Transfer (REST) API for Red Hat Enterprise Virtualization.
Preface
1. About This Guide
2. Audience
3. The Red Hat Enterprise Virtualization Documentation Suite
4. Document Conventions
4.1. Typographic Conventions
4.2. Pull-quote Conventions
4.3. Notes and Warnings
5. Getting Help and Giving Feedback
5.1. Do You Need Help?
5.2. We Need Feedback!
6. Backwards Compatibility Statement
1. Introduction
1.1. Representational State Transfer
1.2. Prerequisites
2. Authentication and Security
2.1. TLS/SSL Certification
2.2. HTTP Authentication
3. Beginner Example
3.1. Access API Entry Point
3.2. List Data Center Collection
3.3. List Host Cluster Collection
3.4. List Logical Networks Collection
3.5. List Host Collection
3.6. Approve Host
3.7. Create NFS Data Storage
3.8. Create NFS ISO Storage
3.9. Attach Storage Domains to Data Center
3.10. Activate Storage Domains
3.11. Create Virtual Machine
3.12. Create Virtual Machine NIC
3.13. Create Virtual Machine Storage Disk
3.14. Attach ISO Image to Virtual Machine
3.15. Start Virtual Machine
3.16. Check System Events
3.17. Example Completion
4. Entry Point
4.1. Product Information
4.2. Link elements
4.3. Special object elements
4.4. Summary element
5. Compatibility Level Versions
6. Capabilities
6.1. Version-Dependent Capabilities
6.1.1. Current Version
6.1.2. Features
6.1.3. CPUs
6.1.4. Power Managers
6.1.5. Fence Types
6.1.6. Storage Types
6.1.7. Storage Domain Types
6.1.8. Virtual Machine Types
6.1.9. Boot Devices
6.1.10. Display Types
6.1.11. NIC Interface Types
6.1.12. Disk Types
6.1.13. OS Types
6.1.14. Disk Formats
6.1.15. Disk Interfaces
6.1.16. Virtual Machine Affinities
6.1.17. Custom Properties
6.1.18. Boot Protocols
6.1.19. Error Handling
6.1.20. Storage Formats
6.1.21. Resource Status States
6.2. Permits
6.3. Scheduling Policies
6.4. Capabilities Example
7. Common Features
7.1. Representations
7.2. Collections
7.2.1. Listing All Resources in a Collection
7.2.2. Listing Extended Resource Sub-Collections
7.2.3. Searching Collections with Queries
7.2.4. Creating a Resource in a Collection
7.3. Resources
7.3.1. Retrieving a Resource
7.3.2. Updating a Resource
7.3.3. Deleting a Resource
7.3.4. Sub-Collection Relationships
7.3.5. XML Element Relationships
7.3.6. Actions
7.3.7. Permissions
7.3.8. Handling Errors
8. Data Centers
8.1. Storage Domains Sub-Collection
8.1.1. Attaching a Storage Domain
8.1.2. Actions
8.2. Force Remove Action
9. Host Clusters
9.1. Networks Sub-Collection
10. Networks
11. Storage Domains
11.1. Storage types
11.1.1. NFS
11.1.2. iSCSI and FCP
11.1.3. LocalFS
11.2. Export Storage Domains
11.3. Files Sub-Collection
11.4. Import Existing Storage Domain
11.5. Delete Storage Domain
12. Hosts
12.1. Power Management
12.2. Memory Management
12.3. Network Interface Sub-Collection
12.3.1. Bonded Interfaces
12.3.2. Network Interface Statistics
12.3.3. Attach Action
12.3.4. Detach Action
12.4. Storage Sub-Collection
12.5. Statistics Sub-Collection
12.6. Actions
12.6.1. Install Action
12.6.2. Activate Action
12.6.3. Fence Action
12.6.4. Deactivate Action
12.6.5. Approve Action
12.6.6. iSCSI Login Action
12.6.7. iSCSI Discover Action
12.6.8. Commit Network Configuration Action
13. Virtual Machines
13.1. Disks Sub-Collection
13.1.1. Disk Cloning
13.1.2. Disk Statistics
13.2. Network Interfaces Sub-Collection
13.2.1. Network Interface Statistics
13.3. CD-ROMs Sub-Collection
13.4. Snapshots Sub-Collection
13.5. Statistics Sub-Collection
13.6. Actions
13.6.1. Start Action
13.6.2. Stop Action
13.6.3. Shutdown Action
13.6.4. Suspend Action
13.6.5. Detach Action
13.6.6. Migrate Action
13.6.7. Export Action
13.6.8. Move Action
13.6.9. Ticket Action
13.6.10. Force Remove Action
14. Templates
14.1. Export Action
15. Virtual Machine Pools
16. Domains
16.1. Domain Users Sub-Collection
16.2. Domain Groups Sub-Collection
17. Groups
18. Roles
18.1. Permits Sub-Collection
19. Users
20. Tags
20.1. Associating Tags With a Host, User or VM
20.2. Parent Tags
21. Events
21.1. Searching Events
21.2. Paginating Events
A. API Usage with cURL
B. Java Keystores
C. Event Codes
D. Timezones
E. Revision History