Red Hat CloudForms 4.5 Red Hat CloudForms REST API

101 Pages·2017·0.42 MB·English

Red Hat CloudForms 4.5
Red Hat CloudForms REST API
Using the Red Hat CloudForms REST API
Last Updated: 2018-04-27

Red Hat CloudForms 4.5 Red Hat CloudForms REST API
Using the Red Hat CloudForms REST API
Red Hat CloudForms Documentation Team
[email protected]
Legal Notice
Copyright © 2018 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is
available at
http://creativecommons.org/licenses/by-sa/3.0/
. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must
provide the URL for the original version.
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, OpenShift, 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 guide provides web services available to integrate Red Hat CloudForms with external
applications. It details the specification of the Red Hat CloudForms RESTful API, which is
implemented as standard REST HTTP requests and responses of content type JSON. If you have a
suggestion for improving this guide or have found an error, please submit a Bugzilla report at
http://bugzilla.redhat.com against Red Hat CloudForms Management Engine for the Documentation
component. Please provide specific details, such as the section number, guide name, and
CloudForms version so we can easily locate the content.
Table of Contents
Table of Contents
.C .H . A. P. .T .E .R . .1 .. .S .P . E. C. .I F. I.C . A. T. I.O . N. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1. HTTP BASICS 7
1.1.1. REST API Entry Point 7
1.1.2. Supported Content Types 7
1.1.3. URL Paths 8
1.1.4. Methods and related URLs 8
1.1.5. Updating Resources 8
1.1.6. Modifying Resource Attributes 9
1.1.7. Return Codes 9
1.1.8. CRUD Examples 10
1.2. AUTHENTICATION 11
1.2.1. Using Basic Authentication 12
1.2.2. Using Authentication Tokens 12
1.3. JSON SPECIFICATION 12
1.3.1. Basic types 13
1.3.2. Common Attributes and Actions 13
1.3.3. Collections 14
1.3.4. Action Specification 15
1.3.5. Forms 17
1.4. QUERY SPECIFICATION 18
1.4.1. Control Attributes 18
1.4.2. Filtering 19
1.4.3. Expanding Collections 19
.C .H . A. P. .T .E .R . .2 .. .R . E. F. E. .R .E . N. C. .E . G. .U . I.D .E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 .1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1. AUTHENTICATION 21
2.2. HTTP HEADERS 21
2.3. LISTING AND QUERYING COLLECTIONS AND SUB-COLLECTIONS 21
2.4. COLLECTION QUERIES 22
2.5. SUB-COLLECTION QUERIES 23
2.6. AVAILABLE ACTIONS 24
2.7. PROVISIONING REQUEST ATTRIBUTES 27
2.7.1. Provisioning Request Attribute Groups 27
2.7.2. Service Catalog Attributes 29
2.7.3. Hardware Attributes 29
2.7.4. Network Attributes 30
2.7.5. Custom Attributes 30
2.7.6. Schedule Attributes 32
2.7.7. Requester Attributes 33
2.7.8. Environment Attributes 34
.C .H . A. P. .T .E .R . .3 .. .E .X . A. M. .P . L. E. S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 .6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1. GENERAL QUERIES 36
3.1.1. Queries 36
3.1.2. Paging Queries 37
3.1.2.1. Request: 37
3.1.2.2. Response: 37
3.1.2.3. Request: 37
3.1.2.4. Response: 37
3.1.2.5. Request: 38
3.1.2.6. Response: 38
3.1.2.7. Request: 38
1
Red Hat CloudForms 4.5 Red Hat CloudForms REST API
3.1.2.8. Response: 39
3.1.3. Querying a Delete Task 39
3.1.3.1. Request: 39
3.1.3.2. Response: 39
3.2. SERVICE CATALOGS 40
3.2.1. Adding a Sample Service Catalog 40
3.2.1.1. Request: 40
3.2.1.2. Response: 40
3.2.2. Adding Multiple Service Catalogs 40
3.2.2.1. Request: 40
3.2.2.2. Response: 41
3.2.3. Assigning Service Templates to Service Catalogs 41
3.2.3.1. Request: 41
3.2.3.2. Response: 42
3.2.4. Editing a Service Catalog 42
3.2.4.1. Request: 42
3.2.4.2. Response: 42
3.2.5. Editing Multiple Service Catalogs 43
3.2.5.1. Request: 43
3.2.5.2. Response: 43
3.2.6. Ordering a Single Service from a Service Catalog 43
3.2.6.1. Request: 43
3.2.6.2. Response: 44
3.2.7. Ordering Multiple Services from a Service Catalog 44
3.2.7.1. Request: 44
3.2.7.2. Response: 45
3.2.8. Unassigning Service Templates from a Service Catalog 46
3.2.8.1. Request: 46
3.2.8.2. Response: 47
3.2.9. Deleting Multiple Service Catalogs 47
3.2.9.1. Request: 47
3.2.9.2. Response: 47
3.3. TAGS 48
3.3.1. Assigning Tags to a Service 48
3.3.1.1. Request: 48
3.3.1.2. Response: 48
3.3.2. Assigning Tags by Name to a Service 49
3.3.2.1. Request: 49
3.3.2.2. Response: 49
3.3.3. Assigning Tags by Reference to a Service 49
3.3.3.1. Request: 49
3.3.3.2. Response: 50
3.3.4. Assigning Tags to a Service Template 50
3.3.4.1. Request: 50
3.3.4.2. Response: 50
3.3.5. Assigning Tags to a Virtual Machine 51
3.3.5.1. Request: 51
3.3.5.2. Response: 51
3.3.6. Assigning Tags by Name to a Virtual Machine 51
3.3.6.1. Request: 51
3.3.6.2. Response: 52
3.3.7. Assigning Tags by Reference to a Virtual Machine 52
3.3.7.1. Request: 52
2
Table of Contents
3.3.7.2. Response: 52
3.3.8. Unassigning Tags from a Service 53
3.3.8.1. Request: 53
3.3.8.2. Response: 53
3.3.9. Unassigning a Tag by Name from a Service 53
3.3.9.1. Request: 53
3.3.9.2. Response: 54
3.3.10. Unassigning a Tag by Reference from a Service 54
3.3.10.1. Request: 54
3.3.10.2. Response: 54
3.3.11. Unassigning Tags from a Service Template 54
3.3.11.1. Request: 54
3.3.11.2. Response: 55
3.4. AUTOMATION REQUESTS 55
3.4.1. Triggering a Single Automation Request 55
3.4.1.1. Request: 55
3.4.1.2. Request: 56
3.4.1.3. Response: 56
3.4.2. Triggering Multiple Automation Requests 57
3.4.2.1. Request: 57
3.4.2.2. Response: 59
3.5. PROVISIONING REQUESTS 61
3.5.1. Triggering a Single Provision Request 61
3.5.1.1. Request: 61
3.5.1.2. Request: 62
3.5.1.3. Response: 62
3.5.2. Triggering Multiple Provision Requests 65
3.5.2.1. Request: 65
3.5.2.2. Response: 67
3.5.3. Monitoring Request 75
3.5.3.1. Response: 75
3.5.4. Placement of Environmental Variables in Provisioning Requests 76
3.5.4.1. Request: 76
3.6. PROVIDERS 77
3.6.1. Creating a Provider 77
3.6.1.1. Request: 77
3.6.1.2. Response: 77
3.6.2. Creating a Provider with Compound Credentials 77
3.6.2.1. Request: 77
3.6.2.2. Response: 78
3.6.3. Refreshing a Provider 78
3.6.3.1. Request: 78
3.6.3.2. Response: 78
3.6.4. Updating a Provider 79
3.6.4.1. Request: 79
3.6.4.2. Response: 79
3.6.5. Deleting a Provider 79
3.6.5.1. Deleting a Single Provider 79
3.6.6. Request: 79
3.6.7. Response: 79
3.6.8. Request: 80
3.6.9. Response: 80
3.6.9.1. Deleting Multiple Providers 80
3
Red Hat CloudForms 4.5 Red Hat CloudForms REST API
3.6.10. Request: 80
3.6.11. Response: 80
3.7. SERVICES 81
3.7.1. Editing a Service 81
3.7.1.1. Request: 81
3.7.1.2. Response: 81
3.7.2. Editing Multiple Services 81
3.7.2.1. Request: 81
3.7.2.2. Response: 82
3.7.3. Editing a Resource with the PATCH Method 82
3.7.3.1. Request: 82
3.7.3.2. Response: 83
3.7.4. Editing a Service with the PUT Method 83
3.7.4.1. Request: 83
3.7.4.2. Response: 83
3.7.5. Retiring a Service Immediately 83
3.7.5.1. Request: 83
3.7.5.2. Response: 84
3.7.5.3. Response: 84
3.7.6. Retiring a Service at a Future Time 84
3.7.6.1. Request: 84
3.7.6.2. Response: 85
3.7.7. Retiring Multiple Services 85
3.7.7.1. Request: 85
3.7.7.2. Response: 85
3.7.8. Deleting Services 86
3.7.8.1. Request: 86
3.7.8.2. Response: 86
3.8. VIRTUAL MACHINES 87
3.8.1. Scanning a Virtual Machine 87
3.8.1.1. Request: 87
3.8.1.2. Response: 87
3.8.1.3. Request: 87
3.8.1.4. Response: 87
3.8.2. Setting the Virtual Machine Owner 88
3.8.2.1. Request: 88
3.8.2.2. Response: 88
3.8.3. Adding an Event to a Virtual Machine 88
3.8.3.1. Request: 88
3.8.3.2. Response: 88
3.8.4. Adding a Lifecycle Event to a Virtual Machine 89
3.8.4.1. Request: 89
3.8.4.2. Response: 89
3.8.5. Starting a Virtual Machine 89
3.8.5.1. Request: 89
3.8.5.2. Response: 89
3.8.6. Querying Task Progress 89
3.8.6.1. Request: 89
3.8.6.2. Response: 90
3.8.7. Stopping a Virtual Machine 90
3.8.7.1. Request: 90
3.8.7.2. Response: 90
3.8.8. Suspending a Virtual Machine 90
4
Table of Contents
3.8.8.1. Request: 90
3.8.8.2. Response: 90
3.8.9. Deleting Virtual Machines 91
3.8.9.1. Deleting a Single Virtual Machine 91
3.8.10. Request: 91
3.8.10.1. Deleting Multiple Virtual Machines 91
3.8.11. Request: 91
3.8.12. Response: 91
3.8.13. Request: 92
3.8.14. Response: 92
3.9. SERVICE TEMPLATES 92
3.9.1. Editing a Service Template 92
3.9.1.1. Request: 92
3.9.1.2. Response: 92
3.9.2. Editing Multiple Service Templates 93
3.9.2.1. Request: 93
3.9.2.2. Response: 93
3.9.3. Deleting Multiple Service Templates 94
3.9.3.1. Request: 94
3.9.3.2. Response: 94
5
Red Hat CloudForms 4.5 Red Hat CloudForms REST API
6