7.4. Resources
7.4.1. Resources
7.4.2. Retrieving a Resource
GET
request on a URI obtained from a collection listing.
Accept
HTTP header to define the MIME type for the response format.
GET /ovirt-engine/api/[collection]/[resource_id] HTTP/1.1 Accept: [MIME type]
All-Content: true
header. The RESTful Service Description Language describes which links support this header.
GET /ovirt-engine/api/[collection]/[resource_id] HTTP/1.1 Accept: [MIME type] All-Content: true
7.4.3. Updating a Resource
PUT
request containing an updated description from a previous GET
request for the resource URI. Details on modifiable properties are found in the individual resource type documentation.
PUT
request requires a Content-Type
header. This informs the API of the representation MIME type in the body content as part of the request.
Accept
HTTP header to define the MIME type for the response format.
PUT /ovirt-engine/api/collection/resource_id HTTP/1.1 Accept: [MIME type] Content-Type: [MIME type] [body]
7.4.4. Deleting a Resource
DELETE
request sent to its URI.
Accept
HTTP header to define the MIME type for the response format.
DELETE /ovirt-engine/api/[collection]/[resource_id] HTTP/1.1 Accept: [MIME type]
DELETE
request to specify additional properties. A DELETE
request with optional body content requires a Content-Type
header to inform the API of the representation MIME type in the body content. If a DELETE
request contains no body content, omit the Content-Type
header.
7.4.5. Sub-Collection Relationships
- Where one parent resource can contain several child resources and vice versa. For example, a virtual machine can contain several disks and some disks are shared among multiple virtual machines.
- Where mapped resources are dependent on a parent resource. Without the parent resource, the dependent resource cannot exist. For example, the link between a virtual machine and snapshots.
- Where mapped resources exist independently from parent resources but data is still associated with the relationship. For example, the link between a cluster and a network.
link rel=
attribute:
GET /ovirt-engine/api/collection/resource_id HTTP/1.1 Accept: application/xml HTTP/1.1 200 OK Content-Type: application/xml <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id"> ... <link rel="subcollection" href="/ovirt-engine/api/collection/resource_id/subcollection"/> ... </resource>
GET /ovirt-engine/api/collection/resource_id/subcollection HTTP/1.1 Accept: application/xml HTTP/1.1 200 OK Content-Type: application/xml <subcollection> <subresource id="subresource_id" href="/ovirt-engine/api/collection/resource_id/subcollection/subresource_id"> ... </subresource> ... </subcollection>
7.4.6. XML Element Relationships
- Backlinks from a resource in a sub-collection to a parent resource; or
- Links between resources with an arbitrary relationship.
Example 7.7. Backlinking from a sub-collection resource to a resource using an XML element
GET /ovirt-engine/api/collection/resource_id/subcollection/subresource_id HTTP/1.1 HTTP/1.1 200 OK Content-Type: application/xml <subcollection> <subresource id="subresource_id" href="/ovirt-engine/api/collection/resource_id/subcollection/subresource_id"> <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id"/> ... </subresource> </subcollection>
7.4.7. Actions
<resource> ... <actions> <link rel="start" href="/ovirt-engine/api/collection/resource_id/start"/> <link rel="stop" href="/ovirt-engine/api/collection/resource_id/stop"/> ... </actions> ... </resource>
POST
request to the supplied URI. The body of the POST
requires an action
representation encapsulating common and task-specific parameters.
Table 7.6. Common action parameters
Element | Description |
---|---|
async | true if the server responds immediately with 202 Accepted and an action representation contains a href link to be polled for completion. |
grace_period | a grace period in milliseconds, which must expire before the action is initiated. |
fault
response.
Content-Type: application/xml
header since the POST
request requires an XML representation in the body content.
202 Accepted
response provides a link to monitor the status of the task:
POST /ovirt-engine/api/collection/resource_id/action HTTP/1.1 Content-Type: application/xml Accept: application/xml <action> <async>true</async> </action> HTTP/1.1 202 Accepted Content-Type: application/xml <action id="action_id" href="/ovirt-engine/api/collection/resource_id/action/action_id"> <async>true</async> ... </action>
GET
on the action URI provides an indication of the status of the asynchronous task.
Table 7.7. Action statuses
Status | Description |
---|---|
pending | Task has not yet started. |
in_progress | Task is in operation. |
complete | Task completed successfully. |
failed | Task failed. The returned action representation would contain a fault describing the failure. |
GET
s are 301 Moved Permanently
redirected back to the target resource.
GET /ovirt-engine/api/collection/resource_id/action/action_id HTTP/1.1 Accept: application/xml HTTP/1.1 200 OK Content-Type: application/xml <action id="action_id" href="/ovirt-engine/api/collection/resource_id/action/action_id"> <status> <state>pending</state> </status> <link rel="parent" /ovirt-engine/api/collection/resource_id"/> <link rel="replay" href="/ovirt-engine/api/collection/resource_id/action"/> </action>
rel
attribute:
Table 7.8. Action relationships
Type | Description |
---|---|
parent | A link back to the resource of this action. |
replay | A link back to the original action URI. POSTing to this URI causes the action to be re-initiated. |
7.4.8. Permissions
permissions
sub-collection. Each permission
contains a user
, an assigned role
and the specified resource. For example:
GET /ovirt-engine/api/collection/resource_id/permissions HTTP/1.1 Accept: application/xml HTTP/1.1 200 OK Content-Type: application/xml <permissions> <permission id="permission-id" href="/ovirt-engine/api/collection/resource_id/permissions/permission_id"> <role id="role_id" href="/ovirt-engine/api/roles/role_id"/> <user id="user_id" href="/ovirt-engine/api/users/user_id"/> <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id"/> </permission> ... </permissions>
POST
request with a permission
representation and a Content-Type: application/xml
header to the resource's permissions
sub-collection. Each new permission requires a role
and a user
:
POST /ovirt-engine/api/collection/resource_id/permissions HTTP/1.1 Content-Type: application/xml Accept: application/xml <permission> <role id="role_id"/> <user id="user_id"/> </permission> HTTP/1.1 201 Created Content-Type: application/xml <permission id="permission_id" href="/ovirt-engine/api/resources/resource_id/permissions/permission_id"> <role id="role_id" href="/ovirt-engine/api/roles/role_id"/> <user id="user_id" href="/ovirt-engine/api/users/user_id"/> <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id"/> </permission>
7.4.9. Handling Errors
fault
representation in the response entity body. The fault contains a reason
and detail
strings. Clients must accommodate failed requests via extracting the fault
or the expected resource representation depending on the response status code. Such cases are clearly indicated in the individual resource documentation.
PUT /ovirt-engine/api/collection/resource_id HTTP/1.1 Accept: application/xml Content-Type: application/xml <resource> <id>id-update-test</id> </resource> HTTP/1.1 409 Conflict Content-Type: application/xml <fault> <reason>Broken immutability constraint</reason> <detail>Attempt to set immutable field: id</detail> </fault>